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.