IPnom Home • Manuals • FreeBSD

 FreeBSD Man Pages

Man Sections:Commands (1)System Calls (2)Library Functions (3)Device Drivers (4)File Formats (5)Miscellaneous (7)System Utilities (8)
Keyword Live Search (10 results max):
 Type in part of a command in the search box.
 


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);

     const char *
     login_getcapstr(login_cap_t *lc, const char *cap, const char *def,
	 const char *error);

     char **
     login_getcaplist(login_cap_t *lc, const char *cap, const char *chars);

     const char *
     login_getpath(login_cap_t *lc, const char *cap, const 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);

     const char *
     login_getstyle(login_cap_t *lc, const char *style, const char *auth);

     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() 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
     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 set-
     tings and default process priorities, 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 rea-
     sons.  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 pro-
     vides a convenient way for a user to set up their preferred login envi-
     ronment 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
     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.  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 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().

			 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 application,
			 but is used indirectly via login_getstyle().

     login_getpath()	 This function returns a list of directories separated
			 by colons `:'.  Capability tags for which this func-
			 tion is called consist of a list of directories sepa-
			 rated 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 suf-
			 fix 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
			 FreeBSD), 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 parameter
			 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
			 parameters, and authorisation type 'auth' and
			 'style', and applies these to determine the authori-
			 sation style that best suites these rules.

			 o   If 'auth' is neither NULL nor an empty string,
			     look for a tag of type "auth-<auth>" in the capa-
			     bility record.  If not present, then look for the
			     default tag "auth=".

			 o   If no valid authorisation list was found from the
			     previous step, then default to "passwd" as the
			     authorisation list.

			 o   If 'style' is not NULL or empty, look for it in
			     the list of authorisation methods found from the
			     previous step.  If 'style' is NULL or an empty
			     string, then default to "passwd" authorisation.

			 o   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 sys-
			 tem, 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 discovery
			 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 ALSO

     crypt(3), getcap(3), login_class(3), login.conf(5), termcap(5)

FreeBSD 5.4		       December 27, 1996		   FreeBSD 5.4

SPONSORED LINKS




Man(1) output converted with man2html , sed , awk