LOGIN_CAP(3)

LOGIN_CAP(3) | Library Functions Manual | LOGIN_CAP(3)

# NAME

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

# LIBRARY

System Utilities Library (libutil, -lutil)

# SYNOPSIS

#include <sys/types.h>
#include <login_cap.h>
login_cap_t *
login_getclass(char *class);
int
login_getcapbool(login_cap_t *lc, const char *cap, unsigned int def);
quad_t
login_getcapnum(login_cap_t *lc, const char *cap, quad_t def, quad_t err);
quad_t
login_getcapsize(login_cap_t *lc, const char *cap, quad_t def, quad_t err);
char *
login_getcapstr(login_cap_t *lc, const char *cap, char *def, char *err);
quad_t
login_getcaptime(login_cap_t *lc, const char *cap, quad_t def, quad_t err);
login_cap_t *
login_getpwclass(struct passwd *pwd);
void
login_close(login_cap_t *lc);
int
setclasscontext(const char *class, unsigned int flags);
int
setusercontext(login_cap_t *lc, const 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.
The login_getpwclass() function is equivalent to:
`login_getclass(pwd ? pwd->pw_class : NULL)`
Once lc has been returned by login_getclass(), any of the other login_*() functions may be called.
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`, 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 various bits available to be or-ed together to make up flags are:

LOGIN_SETGID
  Set the group id. Requires the pwd field be specified.
LOGIN_SETGROUPS
  Set the group membership list by calling initgroups(3). Requires the pwd field be specified.
LOGIN_SETGROUP
  Set the group id and call initgroups(3). Requires the pwd field be specified.
LOGIN_SETLOGIN
  Sets the login name by setlogin(2). Requires the pwd field be specified.
LOGIN_SETPATH
  Sets the `PATH` environment variable.
LOGIN_SETPRIORITY
  Sets the priority by setpriority(2).
LOGIN_SETRESOURCES
  Sets the various system resources by setrlimit(2).
LOGIN_SETUMASK
  Sets the umask by umask(2).
LOGIN_SETUSER
  Sets the user id to uid by setuid(2).
LOGIN_SETENV
  Sets the environment variables as defined by the setenv keyword, by setenv(3).
LOGIN_SETALL
  Sets all of the above.

# SEE ALSO

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

# HISTORY

The login_getclass family of functions are largely based on the BSD/OS implementation of same, and appeared in NetBSD 1.5 by kind permission.

# 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.

June 20, 2013 | NetBSD 8.0