LOGIN_CAP(3) BSD Library Functions Manual LOGIN_CAP(3)NAME
login_close, login_getcapbool, login_getcaplist, login_getcapnum,
login_getcapstr, login_getcapsize, login_getcaptime, login_getclass,
login_getclassbyname, login_getpwclass, login_getstyle,
login_getuserclass, login_setcryptfmt — functions for accessing the login
class capabilities database
LIBRARY
System Utilities Library (libutil, -lutil)
SYNOPSIS
#include <sys/types.h>
#include <login_cap.h>
void
login_close(login_cap_t *lc);
login_cap_t *
login_getclassbyname(const char *nam, const struct passwd *pwd);
login_cap_t *
login_getclass(const char *nam);
login_cap_t *
login_getpwclass(const struct passwd *pwd);
login_cap_t *
login_getuserclass(const struct passwd *pwd);
char *
login_getcapstr(login_cap_t *lc, const char *cap, char *def,
char *error);
char **
login_getcaplist(login_cap_t *lc, const char *cap, const char *chars);
char *
login_getpath(login_cap_t *lc, const char *cap, char *error);
rlim_t
login_getcaptime(login_cap_t *lc, const char *cap, rlim_t def,
rlim_t error);
rlim_t
login_getcapnum(login_cap_t *lc, const char *cap, rlim_t def,
rlim_t error);
rlim_t
login_getcapsize(login_cap_t *lc, const char *cap, rlim_t def,
rlim_t error);
int
login_getcapbool(login_cap_t *lc, const char *cap, int def);
char *
login_getstyle(login_cap_t *lc, char *style, const char *auth);
const char *
login_setcryptfmt(login_cap_t *lc, const char *def, const char *error);
DESCRIPTION
These functions represent a programming interface to the login classes
database provided in login.conf(5). This database contains capabilities,
attributes and default environment and accounting settings for users and
programs running as specific users, as determined by the login class
field within entries in /etc/master.passwd.
Entries in login.conf(5) consist of colon ‘:’ separated fields, the first
field in each record being one or more identifiers for the record (which
must be unique for the entire database), each separated by a '|', and may
optionally include a description as the last 'name'. Remaining fields in
the record consist of keyword/data pairs. Long lines may be continued
with a backslash within empty entries, with the second and subsequent
lines optionally indented for readability. This is similar to the format
used in termcap(5), except that keywords are not limited to two signifi‐
cant characters, and are usually longer for improved readability. As
with termcap entries, multiple records can be linked together (one record
including another) using a field containing tc=<recordid>. The result is
that the entire record referenced by <recordid> replaces the tc= field at
the point at which it occurs. See getcap(3) for further details on the
format and use of a capabilities database.
The login_cap interface provides a convenient means of retrieving login
class records with all tc= references expanded. A program will typically
call one of login_getclass(), login_getpwclass(), login_getuserclass() or
login_getclassbyname() according to its requirements. Each of these
functions returns a login capabilities structure, login_cap_t, which may
subsequently be used to interrogate the database for specific values
using the rest of the API. Once the login_cap_t is of no further use,
the login_close() function should be called to free all resources used.
The structure of login_cap_t is defined in <login_cap.h>, as:
typedef struct {
char *lc_class;
char *lc_cap;
char *lc_style;
} login_cap_t;
The lc_class member contains a pointer to the name of the login class
retrieved. This may not necessarily be the same as the one requested,
either directly via login_getclassbyname(), indirectly via a user's login
record using login_getpwclass(), by class name using login_getclass(), or
login_getuserclass(). If the referenced user has no login class speci‐
fied in /etc/master.passwd, the class name is NULL or an empty string.
If the class specified does not exist in the database, each of these
functions will search for a record with an id of "default", with that
name returned in the lc_class field. In addition, if the referenced user
has a UID of 0 (normally, "root", although the user name is not consid‐
ered) then login_getpwclass() will search for a record with an id of
"root" before it searches for the record with the id of "default".
The lc_cap field is used internally by the library to contain the
expanded login capabilities record. Programs with unusual requirements
may wish to use this with the lower-level getcap(3) style functions to
access the record directly.
The lc_style field is set by the login_getstyle() function to the autho‐
risation style, according to the requirements of the program handling a
login itself.
As noted above, the login_get*class() functions return a login_cap_t
object which is used to access the matching or default record in the
capabilities database. login_getclassbyname() accepts two arguments: the
first one is the record identifier of the record to be retrieved, the
second is an optional directory name. If the first name argument is
NULL, an empty string, or a class that does not exist in the supplemental
or system login class database, then the system default record is
returned instead. If the second dir parameter is NULL, then only the
system login class database is used, but when not NULL, the named direc‐
tory is searched for a login database file called ".login_conf", and
capability records contained within it may override the system defaults.
This scheme allows users to override some login settings from those in
the system login class database by creating class records for their own
private class with a record id of `me'. In the context of a login, it
should be noted that some options cannot by overridden by users for two
reasons; many options, such as resource settings and default process pri‐
orities, require root privileges in order to take effect, and other
fields in the user's file are not be consulted at all during the early
phases of login for security or administrative reasons. See
login.conf(5) for more information on which settings a user is able to
override. Typically, these are limited purely to the user's default
login environment which might otherwise have been overridden in shell
startup scripts in any case. The user's .login_conf merely provides a
convenient way for a user to set up their preferred login environment
before the shell is invoked on login.
If the specified record is NULL, empty or does not exist, and the system
has no "default" record available to fall back to, there is a memory
allocation error or for some reason cgetent(3) is unable to access the
login capabilities database, this function returns NULL.
The functions login_getpwclass(), login_getclass() and
login_getuserclass() retrieve the applicable login class record for the
user's passwd entry or class name by calling login_getclassbyname(). On
failure, NULL is returned. The difference between these functions is
that login_getuserclass() includes the user's overriding .login_conf that
exists in the user's home directory, and login_getpwclass() and
login_getclass() restrict lookup only to the system login class database
in /etc/login.conf. As explained earlier, login_getpwclass() only dif‐
fers from login_getclass() in that it allows the default class for user
'root' as "root" if none has been specified in the password database.
Otherwise, if the passwd pointer is NULL, or the user record has no login
class, then the system "default" entry is retrieved.
Once a program no longer wishes to use a login_cap_t object,
login_close() may be called to free all resources used by the login
class. login_close() may be passed a NULL pointer with no harmful side-
effects.
The remaining functions may be used to retrieve individual capability
records. Each function takes a login_cap_t object as its first parame‐
ter, a capability tag as the second, and remaining parameters being
default and error values that are returned if the capability is not
found. The type of the additional parameters passed and returned depend
on the type of capability each deals with, be it a simple string, a list,
a time value, a file or memory size value, a path (consisting of a colon-
separated list of directories) or a boolean flag. The manpage for
login.conf(5) deals in specific tags and their type.
Note that with all functions in this group, you should not call free(3)
on any pointers returned. Memory allocated during retrieval or process‐
ing of capability tags is automatically reused by subsequent calls to
functions in this group, or deallocated on calling login_close().
login_getcapstr() This function returns a simple string capability.
If the string is not found, then the value in def is
returned as the default value, or if an error
occurs, the value in the error parameter is
returned.
login_getcaplist() This function returns the value corresponding to the
named capability tag as a list of values in a NULL
terminated array. Within the login class database,
some tags are of type list, which consist of one or
more comma- or space separated values. Usually,
this function is not called directly from an appli‐
cation, but is used indirectly via login_getstyle().
login_getpath() This function returns a list of directories sepa‐
rated by colons ‘&:’. Capability tags for which
this function is called consist of a list of direc‐
tories separated by spaces.
login_getcaptime() This function returns a time value associated with a
particular capability tag with the value expressed
in seconds (the default), minutes, hours, days,
weeks or (365 day) years or any combination of
these. A suffix determines the units used: S for
seconds, M for minutes, H for hours, D for days, W
for weeks and Y for 365 day years. Case of the
units suffix is ignored.
Time values are normally used for setting resource,
accounting and session limits. If supported by the
operating system and compiler (which is true of
DragonFly), the value returned is a quad (long
long), of type rlim_t. A value "inf" or "infinity"
may be used to express an infinite value, in which
case RLIM_INFINITY is returned.
login_getcapnum() This function returns a numeric value for a tag,
expressed either as tag=<value> or the standard
cgetnum() format tag#<value>. The first format
should be used in preference to the second, the sec‐
ond format is provided for compatibility and consis‐
tency with the getcap(3) database format where
numeric types use the ‘#’ as the delimiter for
numeric values. If in the first format, then the
value given may be "inf" or "infinity" which results
in a return value of RLIM_INFINITY. If the given
capability tag cannot be found, the def parameter is
returned, and if an error occurs, the error parame‐
ter is returned.
login_getcapsize()login_getcapsize() returns a value representing a
size (typically, file or memory) which may be
expressed as bytes (the default), 512 byte blocks,
kilobytes, megabytes, gigabytes, and on systems that
support the long long type, terabytes. The suffix
used determines the units, and multiple values and
units may be used in combination (e.g. 1m500k = 1.5
megabytes). A value with no suffix is interpreted
as bytes, B as 512-byte blocks, K as kilobytes, M
as megabytes, G as gigabytes and T as terabytes.
Case is ignored. The error value is returned if
there is a login capabilities database error, if an
invalid suffix is used, or if a numeric value cannot
be interpreted.
login_getcapbool() This function returns a boolean value tied to a par‐
ticular flag. It returns 0 if the given capability
tag is not present or is negated by the presence of
a "tag@" (See getcap(3) for more information on
boolean flags), and returns 1 if the tag is found.
login_getstyle() This function is used by the login authorisation
system to determine the style of login available in
a particular case. The function accepts three
parameters, the login_cap entry itself and two
optional parameters, and authorisation type 'auth'
and 'style', and applies these to determine the
authorisation style that best suites these rules.
· If 'auth' is neither NULL nor an empty string,
look for a tag of type "auth-<auth>" in the
capability record. If not present, then look
for the default tag "auth=".
· If no valid authorisation list was found from
the previous step, then default to "passwd" as
the authorisation list.
· If 'style' is not NULL or empty, look for it in
the list of authorisation methods found from the
pprevious step. If 'style' is NULL or an empty
string, then default to "passwd" authorisation.
· If 'style' is found in the chosen list of autho‐
risation methods, then return that, otherwise
return NULL.
This scheme allows the administrator to determine
the types of authorisation methods accepted by the
system, depending on the means by which the access
occurs. For example, the administrator may require
skey or kerberos as the authentication method used
for access to the system via the network, and stan‐
dard methods via direct dialup or console logins,
significantly reducing the risk of password discov‐
ery by "snooping" network packets.
login_setcryptfmt() The login_setcryptfmt() function is used to set the
crypt(3) format using the ‘passwd_format’ configura‐
tion entry. If no entry is found, def is taken to
be used as the fallback. If calling
crypt_set_format(3) on the specifier fails, error is
returned to indicate this.
SEE ALSOcrypt(3), getcap(3), login_class(3), login.conf(5), termcap(5)BSD December 27, 1996 BSD
