Don't use .Fn for getcap. Reference it with .Xr instead.
[dragonfly.git] / lib / libutil / login_cap.3
1.\" Copyright (c) 1995 David Nugent <>
2.\" All rights reserved.
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, is permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice immediately at the beginning of the file, without modification,
9.\" this list of conditions, and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\" 3. This work was done expressly for inclusion into FreeBSD. Other use
14.\" is permitted provided this notation is included.
15.\" 4. Absolutely no warranty of function or purpose is made by the author
16.\" David Nugent.
17.\" 5. Modifications may be freely made to this file providing the above
18.\" conditions are met.
20.\" $FreeBSD: src/lib/libutil/login_cap.3,v 2002/12/29 16:35:36 schweikh Exp $
2645b4e7 21.\" $DragonFly: src/lib/libutil/login_cap.3,v 1.6 2008/10/01 11:01:02 swildner Exp $
23.Dd December 27, 1996
26.Sh NAME
27.Nm login_close ,
28.Nm login_getcapbool ,
29.Nm login_getcaplist ,
30.Nm login_getcapnum ,
31.Nm login_getcapstr ,
32.Nm login_getcapsize ,
33.Nm login_getcaptime ,
34.Nm login_getclass ,
35.Nm login_getclassbyname ,
36.Nm login_getpwclass ,
37.Nm login_getstyle ,
38.Nm login_getuserclass ,
39.Nm login_setcryptfmt
40.Nd "functions for accessing the login class capabilities database"
42.Lb libutil
44.In sys/types.h
45.In login_cap.h
46.Ft void
47.Fn login_close "login_cap_t *lc"
48.Ft login_cap_t *
49.Fn login_getclassbyname "const char *nam" "const struct passwd *pwd"
50.Ft login_cap_t *
51.Fn login_getclass "const char *nam"
52.Ft login_cap_t *
53.Fn login_getpwclass "const struct passwd *pwd"
54.Ft login_cap_t *
55.Fn login_getuserclass "const struct passwd *pwd"
56.Ft char *
57.Fn login_getcapstr "login_cap_t *lc" "const char *cap" "char *def" "char *error"
58.Ft char **
59.Fn login_getcaplist "login_cap_t *lc" "const char *cap" "const char *chars"
60.Ft char *
61.Fn login_getpath "login_cap_t *lc" "const char *cap" "char *error"
62.Ft rlim_t
63.Fn login_getcaptime "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
64.Ft rlim_t
65.Fn login_getcapnum "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
66.Ft rlim_t
67.Fn login_getcapsize "login_cap_t *lc" "const char *cap" "rlim_t def" "rlim_t error"
68.Ft int
69.Fn login_getcapbool "login_cap_t *lc" "const char *cap" "int def"
70.Ft char *
71.Fn login_getstyle "login_cap_t *lc" "char *style" "const char *auth"
72.Ft const char *
73.Fn login_setcryptfmt "login_cap_t *lc" "const char *def" "const char *error"
75These functions represent a programming interface to the login
76classes database provided in
77.Xr login.conf 5 .
78This database contains capabilities, attributes and default environment
79and accounting settings for users and programs running as specific users,
80as determined by the login class field within entries in
81.Pa /etc/master.passwd .
83Entries in
84.Xr login.conf 5
85consist of colon
86.Ql \&:
87separated fields, the first field in each record being one or more
88identifiers for the record (which must be unique for the entire database),
89each separated by a '|', and may optionally include a description as
90the last 'name'.
91Remaining fields in the record consist of keyword/data pairs.
92Long lines may be continued with a backslash within empty entries,
93with the second and subsequent lines optionally indented for readability.
94This is similar to the format used in
95.Xr termcap 5 ,
96except that keywords are not limited to two significant characters,
97and are usually longer for improved readability.
98As with termcap entries, multiple records can be linked together
99(one record including another) using a field containing tc=<recordid>.
100The result is that the entire record referenced by <recordid> replaces
101the tc= field at the point at which it occurs.
103.Xr getcap 3
104for further details on the format and use of a capabilities database.
107.Nm login_cap
108interface provides a convenient means of retrieving login class
109records with all tc= references expanded.
110A program will typically call one of
111.Fn login_getclass ,
112.Fn login_getpwclass ,
113.Fn login_getuserclass
115.Fn login_getclassbyname
116according to its requirements.
117Each of these functions returns a login capabilities structure,
118.Ft login_cap_t ,
119which may subsequently be used to interrogate the database for
120specific values using the rest of the API.
121Once the login_cap_t is of no further use, the
122.Fn login_close
123function should be called to free all resources used.
125The structure of login_cap_t is defined in
126.In login_cap.h ,
128.Bd -literal -offset indent
129typedef struct {
130 char *lc_class;
131 char *lc_cap;
132 char *lc_style;
133} login_cap_t;
137.Ar lc_class
138member contains a pointer to the name of the login class
140This may not necessarily be the same as the one requested,
141either directly via
142.Fn login_getclassbyname ,
143indirectly via a user's login record using
144.Fn login_getpwclass ,
145by class name using
146.Fn login_getclass ,
148.Fn login_getuserclass .
149If the referenced user has no login class specified in
150.Pa /etc/master.passwd ,
151the class name is NULL or an empty string.
152If the class
153specified does not exist in the database, each of these
154functions will search for a record with an id of "default",
155with that name returned in the
156.Ar lc_class
158In addition, if the referenced user has a UID of 0 (normally,
159"root", although the user name is not considered) then
160.Fn login_getpwclass
161will search for a record with an id of "root" before it searches
162for the record with the id of "default".
165.Ar lc_cap
166field is used internally by the library to contain the
167expanded login capabilities record.
168Programs with unusual requirements may wish to use this
169with the lower-level
2645b4e7 170.Xr getcap 3
171style functions to access the record directly.
174.Ar lc_style
175field is set by the
176.Fn login_getstyle
177function to the authorisation style, according to the requirements
178of the program handling a login itself.
180As noted above, the
1d6f2920 181.Fn login_get*class
182functions return a login_cap_t object which is used to access
183the matching or default record in the capabilities database.
1d6f2920 184.Fn login_getclassbyname
185accepts two arguments: the first one is the record identifier of the
186record to be retrieved, the second is an optional directory name.
187If the first
188.Ar name
189argument is NULL, an empty string, or a class that does not exist
190in the supplemental or system login class database, then the system
191.Em default
192record is returned instead.
193If the second
194.Ar dir
195parameter is NULL, then only the system login class database is
196used, but when not NULL, the named directory is searched for
197a login database file called ".login_conf", and capability records
198contained within it may override the system defaults.
199This scheme allows users to override some login settings from
200those in the system login class database by creating class records
201for their own private class with a record id of `me'.
202In the context of a
203.Em login ,
204it should be noted that some options cannot by overridden by
205users for two reasons; many options, such as resource settings
206and default process priorities, require root privileges
207in order to take effect, and other fields in the user's file are
208not be consulted at all during the early phases of login for
209security or administrative reasons.
211.Xr login.conf 5
212for more information on which settings a user is able to override.
213Typically, these are limited purely to the user's default login
214environment which might otherwise have been overridden in shell
215startup scripts in any case.
216The user's
217.Pa .login_conf
218merely provides a convenient way for a user to set up their preferred
219login environment before the shell is invoked on login.
221If the specified record is NULL, empty or does not exist, and the
222system has no "default" record available to fall back to, there is a
223memory allocation error or for some reason
224.Xr cgetent 3
225is unable to access the login capabilities database, this function
226returns NULL.
228The functions
229.Fn login_getpwclass ,
230.Fn login_getclass
232.Fn login_getuserclass
233retrieve the applicable login class record for the user's passwd
234entry or class name by calling
235.Fn login_getclassbyname .
236On failure, NULL is returned.
237The difference between these functions is that
238.Fn login_getuserclass
239includes the user's overriding
240.Pa .login_conf
241that exists in the user's home directory, and
242.Fn login_getpwclass
244.Fn login_getclass
245restrict lookup only to the system login class database in
246.Pa /etc/login.conf .
247As explained earlier,
248.Fn login_getpwclass
249only differs from
250.Fn login_getclass
251in that it allows the default class for user 'root' as "root"
252if none has been specified in the password database.
253Otherwise, if the passwd pointer is NULL, or the user record
254has no login class, then the system "default" entry is retrieved.
256Once a program no longer wishes to use a login_cap_t object,
257.Fn login_close
258may be called to free all resources used by the login class.
259.Fn login_close
260may be passed a NULL pointer with no harmful side-effects.
262The remaining functions may be used to retrieve individual
263capability records.
264Each function takes a login_cap_t object as its first parameter,
265a capability tag as the second, and remaining parameters being
266default and error values that are returned if the capability is
267not found.
268The type of the additional parameters passed and returned depend
269on the
270.Em type
271of capability each deals with, be it a simple string, a list,
272a time value, a file or memory size value, a path (consisting of
273a colon-separated list of directories) or a boolean flag.
274The manpage for
275.Xr login.conf 5
276deals in specific tags and their type.
278Note that with all functions in this group, you should not call
279.Xr free 3
280on any pointers returned.
281Memory allocated during retrieval or processing of capability
282tags is automatically reused by subsequent calls to functions
283in this group, or deallocated on calling
284.Fn login_close .
285.Bl -tag -width "login_getcaplist()"
286.It Fn login_getcapstr
287This function returns a simple string capability.
288If the string is not found, then the value in
289.Ar def
290is returned as the default value, or if an error
291occurs, the value in the
292.Ar error
293parameter is returned.
294.It Fn login_getcaplist
295This function returns the value corresponding to the named
296capability tag as a list of values in a NULL terminated
298Within the login class database, some tags are of type
299.Em list ,
300which consist of one or more comma- or space separated
302Usually, this function is not called directly from an
303application, but is used indirectly via
304.Fn login_getstyle .
305.It Fn login_getpath
306This function returns a list of directories separated by colons
307.Ql &: .
308Capability tags for which this function is called consist of a list of
309directories separated by spaces.
310.It Fn login_getcaptime
311This function returns a
312.Em time value
313associated with a particular capability tag with the value expressed
314in seconds (the default), minutes, hours, days, weeks or (365 day)
315years or any combination of these.
316A suffix determines the units used: S for seconds, M for minutes,
317H for hours, D for days, W for weeks and Y for 365 day years.
318Case of the units suffix is ignored.
320Time values are normally used for setting resource, accounting and
321session limits.
322If supported by the operating system and compiler (which is true of
9bb2a92d 323.Dx ) ,
324the value returned is a quad (long long), of type
325.Em rlim_t .
326A value "inf" or "infinity" may be used to express an infinite
327value, in which case RLIM_INFINITY is returned.
328.It Fn login_getcapnum
329This function returns a numeric value for a tag, expressed either as
330tag=<value> or the standard
331.Fn cgetnum
332format tag#<value>.
333The first format should be used in preference to the second, the
334second format is provided for compatibility and consistency with the
335.Xr getcap 3
336database format where numeric types use the
337.Ql \&#
338as the delimiter for numeric values.
339If in the first format, then the value given may be "inf" or
340"infinity" which results in a return value of RLIM_INFINITY.
341If the given capability tag cannot be found, the
342.Ar def
343parameter is returned, and if an error occurs, the
344.Ar error
345parameter is returned.
346.It Fn login_getcapsize
347.Fn login_getcapsize
348returns a value representing a size (typically, file or memory)
349which may be expressed as bytes (the default), 512 byte blocks,
350kilobytes, megabytes, gigabytes, and on systems that support the
351.Ar long long
352type, terabytes.
353The suffix used determines the units, and multiple values and
354units may be used in combination (e.g. 1m500k = 1.5 megabytes).
355A value with no suffix is interpreted as bytes, B as 512-byte
356blocks, K as kilobytes, M as megabytes, G as gigabytes and T as
358Case is ignored.
359The error value is returned if there is a login capabilities database
360error, if an invalid suffix is used, or if a numeric value cannot be
362.It Fn login_getcapbool
363This function returns a boolean value tied to a particular flag.
364It returns 0 if the given capability tag is not present or is
365negated by the presence of a "tag@" (See
366.Xr getcap 3
367for more information on boolean flags), and returns 1 if the tag
368is found.
369.It Fn login_getstyle
370This function is used by the login authorisation system to determine
371the style of login available in a particular case.
372The function accepts three parameters, the login_cap entry itself and
373two optional parameters, and authorisation type 'auth' and 'style', and
374applies these to determine the authorisation style that best suites
375these rules.
376.Bl -bullet
378If 'auth' is neither NULL nor an empty string, look for a tag of type
379"auth-<auth>" in the capability record.
380If not present, then look for the default tag "auth=".
382If no valid authorisation list was found from the previous step, then
383default to "passwd" as the authorisation list.
385If 'style' is not NULL or empty, look for it in the list of authorisation
386methods found from the pprevious step.
387If 'style' is NULL or an empty string, then default to "passwd"
390If 'style' is found in the chosen list of authorisation methods, then
391return that, otherwise return NULL.
394This scheme allows the administrator to determine the types of
395authorisation methods accepted by the system, depending on the
396means by which the access occurs.
397For example, the administrator may require skey or kerberos as
398the authentication method used for access to the system via the
399network, and standard methods via direct dialup or console
400logins, significantly reducing the risk of password discovery
401by "snooping" network packets.
402.It Fn login_setcryptfmt
404.Fn login_setcryptfmt
405function is used to set the
406.Xr crypt 3
407format using the
408.Ql passwd_format
409configuration entry.
410If no entry is found,
411.Fa def
412is taken to be used as the fallback.
413If calling
414.Xr crypt_set_format 3
415on the specifier fails,
416.Fa error
417is returned to indicate this.
420.Xr crypt 3 ,
421.Xr getcap 3 ,
422.Xr login_class 3 ,
423.Xr login.conf 5 ,
424.Xr termcap 5