xref: /netbsd/lib/libutil/login_cap.3 (revision c4a72b64) 
1.\" $NetBSD: login_cap.3,v 1.12 2002/10/01 19:36:30 wiz Exp $
2.\"
3.\" Copyright (c) 1996,1997 Berkeley Software Design, Inc. All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, 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. All advertising materials mentioning features or use of this software
14.\"    must display the following acknowledgement:
15.\"	This product includes software developed by Berkeley Software Design,
16.\"	Inc.
17.\" 4. The name of Berkeley Software Design, Inc.  may not be used to endorse
18.\"    or promote products derived from this software without specific prior
19.\"    written permission.
20.\"
21.\" THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN, INC. ``AS IS'' AND
22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24.\" ARE DISCLAIMED.  IN NO EVENT SHALL BERKELEY SOFTWARE DESIGN, INC. BE LIABLE
25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31.\" SUCH DAMAGE.
32.\"
33.\" BSDI login_cap.3,v 1.4 1997/11/07 16:22:27 jch Exp
34.\"
35.Dd January 13, 2000
36.Dt LOGIN_CAP 3
37.Os
38.Sh NAME
39.Nm login_getclass ,
40.Nm login_getcapbool ,
41.Nm login_getcapnum ,
42.Nm login_getcapsize ,
43.Nm login_getcapstr ,
44.Nm login_getcaptime ,
45.Nm login_close ,
46.Nm setclasscontext ,
47.Nm setusercontext
48.Nd query login.conf database about a user class
49.Sh LIBRARY
50.Lb libutil
51.Sh SYNOPSIS
52.Fd #include \*[Lt]sys/types.h\*[Gt]
53.Fd #include \*[Lt]login_cap.h\*[Gt]
54.Ft login_cap_t *
55.Fn login_getclass "char *class"
56.Ft int
57.Fn login_getcapbool "login_cap_t *lc" "char *cap" "u_int def"
58.Ft quad_t
59.Fn login_getcapnum "login_cap_t *lc" "char *cap" "quad_t def" "quad_t err"
60.Ft quad_t
61.Fn login_getcapsize "login_cap_t *lc" "char *cap" "quad_t def" "quad_t err"
62.Ft char *
63.Fn login_getcapstr "login_cap_t *lc" "char *cap" "char *def" "char *err"
64.Ft quad_t
65.Fn login_getcaptime "login_cap_t *lc" "char *cap" "quad_t def" "quad_t err"
66.Ft void
67.Fn login_close "login_cap_t *lc"
68.Ft int
69.Fn setclasscontext "char *class" "u_int flags"
70.Ft int
71.Fn setusercontext "login_cap_t *lc" "struct passwd *pwd" "uid_t uid" "u_int flags"
72.Sh DESCRIPTION
73The
74.Fn login_getclass
75function extracts the entry specified by
76.Ar class
77(or
78.Li default
79if
80.Ar class
81is NULL or the empty string)
82from
83.Pa /etc/login.conf
84(see
85.Xr login.conf 5 ) .
86If the entry is found, a
87.Li login_cap_t
88pointer is returned.
89NULL is returned if the user class is not found.
90When the
91.Li login_cap_t
92structure is no longer needed, it should be freed by the
93.Fn login_close
94function.
95.Pp
96Once
97.Ar lc
98has been returned by
99.Fn login_getclass ,
100any of the other
101.Fn login_*
102functions may be called.
103.Pp
104The
105.Fn login_getcapnum ,
106.Fn login_getcapsize ,
107.Fn login_getcapstr ,
108and
109.Fn login_getcaptime
110functions all query the database entry for a field named
111.Ar cap .
112If the field is found, its value is returned.
113If the field is not found, the value specified by
114.Ar def
115is returned.
116If an error is encountered while trying to find the field,
117.Ar err
118is returned.
119See
120.Xr login.conf 5
121for a discussion of the various textual forms the value may take.
122The
123.Fn login_getcapbool
124function is slightly different.
125It returns
126.Ar def
127if no capabilities were found for this class (typically meaning that
128the default class was used and the
129.Li /etc/login.conf
130file is missing).
131It returns a non-zero value if
132.Ar cap ,
133with no value, was found,
134zero otherwise.
135.Pp
136The
137.Fn setclasscontext
138function takes
139.Ar class ,
140the name of a user class,
141and sets the resources defined by that class according to
142.Ar flags .
143Only the
144.Dv LOGIN_SETPATH ,
145.Dv LOGIN_SETPRIORITY ,
146.Dv LOGIN_SETRESOURCES ,
147and
148.Dv LOGIN_SETUMASK
149bits are used.
150(See
151.Fn setusercontext
152below).
153It returns 0 on success and -1 on failure.
154.Pp
155The
156.Fn setusercontext
157function
158sets the resources according to
159.Ar flags .
160The
161.Ar lc
162argument, if not NULL, contains the class information that should
163be used.
164The
165.Ar pwd
166argument, if not NULL, provides information about the user.
167Both
168.Ar lc
169and
170.Ar pwd
171cannot be NULL.
172The
173.Ar uid
174argument is used in place of the user id contained in the
175.Ar pwd
176structure when calling
177.Xr setuid 2 .
178The various bits available to be or-ed together to make up
179.Ar flags
180are:
181.Bl -tag -width LOGIN_SETRESOURCESXX
182.It LOGIN_SETGROUP
183Set the group id and call
184.Xr initgroups 3 .
185Requires the
186.Ar pwd
187field be specified.
188.It LOGIN_SETLOGIN
189Sets the login name by
190.Xr setlogin 2 .
191Requires the
192.Ar pwd
193field be specified.
194.It LOGIN_SETPATH
195Sets the
196.Ev PATH
197environment variable.
198.It LOGIN_SETPRIORITY
199Sets the priority by
200.Xr setpriority 2 .
201.It LOGIN_SETRESOURCES
202Sets the various system resources by
203.Xr setrlimit 2 .
204.It LOGIN_SETUMASK
205Sets the umask by
206.Xr umask 2 .
207.It LOGIN_SETUSER
208Sets the user id to
209.Ar uid
210by
211.Xr setuid 2 .
212.It LOGIN_SETENV
213Sets the environment variables as defined by the setenv keyword, by
214.Xr setenv 3 .
215.It LOGIN_SETALL
216Sets all of the above.
217.El
218.Sh SEE ALSO
219.Xr setlogin 2 ,
220.Xr setpriority 2 ,
221.Xr setrlimit 2 ,
222.Xr setuid 2 ,
223.Xr umask 2 ,
224.Xr initgroups 3 ,
225.Xr secure_path 3 ,
226.Xr login.conf 5
227.Sh HISTORY
228The
229.Nm
230family of functions are largely based on the
231.Bsx
232implementation of same, and appeared in
233.Nx 1.5
234by kind permission.
235.Sh CAVEATS
236The string returned by
237.Fn login_getcapstr
238is allocated via
239.Xr malloc 3
240when the specified capability is present and thus it is the responsibility
241of the caller to
242.Fn free
243this space.
244However, if the capability was not found or an error occurred and
245.Fa def
246or
247.Fa err
248(whichever is relevant) are non-NULL the returned value is simply what
249was passed in to
250.Fn login_getcapstr .
251Therefore it is not possible to blindly
252.Fn free
253the return value without first checking it against
254.Fa def
255and
256.Fa err .
257.Pp
258The same warnings set forth in
259.Xr setlogin 2
260apply to
261.Fn setusercontext
262when the
263.Dv LOGIN_SETLOGIN
264flag is used.
265Specifically, changing the login name affects all processes in the current
266session, not just the current process.
267See
268.Xr setlogin 2
269for more information.
270