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 thepath
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 to0
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 to022
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.