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 significant 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 users login record using login_getpwclass, by class name using login_getclass, or login_getuserclass. If the referenced user has no login class specified 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 considered) 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 style functions to access the record directly.
The lc_style field is set by the login_getstyle function to the authorisation 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. The login_getclassbyname function accepts two arguments: the first one is the record identifier of the record to be retrieved, the second is an optional pointer to a passwd structure. 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 pwd parameter is NULL, then only the system login class database is used. However, if the pwd parameter and the value of pwd->pw_dir are both not NULL, then the directory contained in pwd->pw_dir 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 priorities, require root privileges in order to take effect, and other fields in the users 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 users default login environment which might otherwise have been overridden in shell startup scripts in any case. The users .login_conf merely provides a convenient way for a user to set up their preferred login environment before the shell is invoked on login. Note that access to the /etc/login.conf and .login_conf files will only be performed subject to the security checks documented in _secure_path(3) for the uids 0 and pwd->pw_uid respectively.
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 users 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 users overriding .login_conf that exists in the users 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 differs 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. The login_close function 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 parameter, 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 processing of capability tags is automatically reused by subsequent calls to functions in this group, or deallocated on calling login_close.