LOGIN_GETCLASS(3) | Library Functions Manual | LOGIN_GETCLASS(3)

# NAME

`login_getclass`, `login_getstyle`, `login_getcapbool`, `login_getcapnum`, `login_getcapsize`, `login_getcapstr`, `login_getcaptime`, `login_close`, `setclasscontext`, `setusercontext` — query login.conf database about a user class

# SYNOPSIS

`#include <sys/types.h>`
`#include <login_cap.h>`

login_cap_t *
`login_getclass`(char *class);

char *
`login_getstyle`(login_cap_t *lc, char *style, char *type);

int
`login_getcapbool`(login_cap_t *lc, char *cap, unsigned int def);

quad_t
`login_getcapnum`(login_cap_t *lc, char *cap, quad_t def, quad_t err);

quad_t
`login_getcapsize`(login_cap_t *lc, char *cap, quad_t def, quad_t err);

char *
`login_getcapstr`(login_cap_t *lc, char *cap, char *def, char *err);

quad_t
`login_getcaptime`(login_cap_t *lc, char *cap, quad_t def, quad_t err);

void
`login_close`(login_cap_t *lc);

int
`setclasscontext`(char *class, unsigned int flags);

int
`setusercontext`(login_cap_t *lc, struct passwd *pwd, uid_t uid, unsigned int flags);

# DESCRIPTION

The `login_getclass`() function extracts the entry specified by class (or `default` if class is `NULL` or the empty string) from /etc/login.conf (see login.conf(5)). If the entry is found, a login_cap_t pointer is returned. `NULL` is returned if the user class is not found. When the login_cap_t structure is no longer needed, it should be freed by the `login_close`() function.

Once lc has been returned by `login_getclass`(), any of the other `login_*`() functions may be called. The `login_getstyle`() function is used to obtain the style of authentication that should be used for this user class. The style argument may either be `NULL` or the desired style of authentication. If `NULL`, the first available authentication style will be used. The type argument refers to the type of authentication being performed. This is used to override the standard `auth` entry in the database. By convention this should be of the form "auth-type". Future releases may remove the requirement for the "auth-" prefix and add it if it is missing. If type is `NULL` then only "auth" will be looked at (see login.conf(5)). The `login_getstyle`() function will return `NULL` if the desired style of authentication is not available, or if no style is available.

The `login_getcapnum`(), `login_getcapsize`(), `login_getcapstr`(), and `login_getcaptime`() functions all query the database entry for a field named cap. If the field is found, its value is returned. If the field is not found, the value specified by def is returned. If an error is encountered while trying to find the field, err is returned. See login.conf(5) for a discussion of the various textual forms the value may take. The `login_getcapbool`() function is slightly different. It returns def if no capabilities were found for this class (typically meaning that the default class was used and the /etc/login.conf file is missing). It returns a non-zero value if cap, with no value, was found, zero otherwise.

The `setclasscontext`() function takes class, the name of a user class, and sets the resources defined by that class according to flags. Only the `LOGIN_SETPATH`, `LOGIN_SETPRIORITY`, `LOGIN_SETRESOURCES`, `LOGIN_SETRTABLE`, and `LOGIN_SETUMASK` bits are used (see `setusercontext`() below). It returns 0 on success and -1 on failure.

The `setusercontext`() function sets the resources according to flags. The lc argument, if not `NULL`, contains the class information that should be used. The pwd argument, if not `NULL`, provides information about the user. Both lc and pwd cannot be `NULL`. The uid argument is used in place of the user ID contained in the pwd structure when calling setuid(2). The `setusercontext`() function returns 0 on success and -1 on failure. The various bits available to be or-ed together to make up flags are:

`LOGIN_SETENV`
  Sets environment variables specified by the `setenv` keyword.
`LOGIN_SETGROUP`
  Set the group ID and call initgroups(3) if the pwd argument is non-NULL.
`LOGIN_SETLOGIN`
  Sets the login name using setlogin(2) if the pwd argument is non-NULL.
`LOGIN_SETPATH`
  Sets the `PATH` environment variable to the value of the `path` keyword if specified, or to the value of `_PATH_DEFPATH` in `<paths.h>` if not.
`LOGIN_SETPRIORITY`
  Sets the priority, using setpriority(2), to the value of the `priority` keyword if specified, or to `0` if not.
`LOGIN_SETRESOURCES`
  Sets the various system resources using setrlimit(2).
`LOGIN_SETRTABLE`
  Sets the routing table to the value of the `rtable` keyword, if specified, using setrtable(2).
`LOGIN_SETUMASK`
  Sets the umask, using umask(2), to the value of the `umask` keyword if specified, or to `022` if not.
`LOGIN_SETUSER`
  Sets the user ID to uid using setuid(2).
`LOGIN_SETALL`
  Sets all of the above.

# SEE ALSO

setlogin(2), setpriority(2), setrlimit(2), setrtable(2), setuid(2), umask(2), initgroups(3), login.conf(5)

# HISTORY

The `login_getclass` function first appeared in OpenBSD 2.8.

# CAVEATS

The string returned by `login_getcapstr`() is allocated via malloc(3) when the specified capability is present and thus it is the responsibility of the caller to `free`() this space. However, if the capability was not found or an error occurred and def or err (whichever is relevant) are non-NULL the returned value is simply what was passed in to `login_getcapstr`(). Therefore it is not possible to blindly `free`() the return value without first checking it against def and err.

The same warnings set forth in setlogin(2) apply to `setusercontext`() when the `LOGIN_SETLOGIN` flag is used. Specifically, changing the login name affects all processes in the current session, not just the current process. See setlogin(2) for more information.

March 18, 2024 | Debian