1.\" $NetBSD: login_cap.3,v 1.10 2002/02/07 07:00:52 ross 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. If the field is not 113found, 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. It returns 125.Ar def 126if no capabilities were found for this class (typically meaning that 127the default class was used and the 128.Li /etc/login.conf 129file is missing). 130It returns a non-zero value if 131.Ar cap , 132with no value, was found, 133zero otherwise. 134.Pp 135The 136.Fn setclasscontext 137function takes 138.Ar class , 139the name of a user class, 140and sets the resources defined by that class according to 141.Ar flags . 142Only the 143.Dv LOGIN_SETPATH , 144.Dv LOGIN_SETPRIORITY , 145.Dv LOGIN_SETRESOURCES , 146and 147.Dv LOGIN_SETUMASK 148bits are used. (See 149.Fn setusercontext 150below). 151It returns 0 on success and -1 on failure. 152.Pp 153The 154.Fn setusercontext 155function 156sets the resources according to 157.Ar flags . 158The 159.Ar lc 160argument, if not NULL, contains the class information that should 161be used. 162The 163.Ar pwd 164argument, if not NULL, provides information about the user. 165Both 166.Ar lc 167and 168.Ar pwd 169cannot be NULL. 170The 171.Ar uid 172argument is used in place of the user id contained in the 173.Ar pwd 174structure when calling 175.Xr setuid 2 . 176The various bits available to be or-ed together to make up 177.Ar flags 178are: 179.Bl -tag -width LOGIN_SETRESOURCESXX 180.It LOGIN_SETGROUP 181Set the group id and call 182.Xr initgroups 3 . 183Requires the 184.Ar pwd 185field be specified. 186.It LOGIN_SETLOGIN 187Sets the login name by 188.Xr setlogin 2 . 189Requires the 190.Ar pwd 191field be specified. 192.It LOGIN_SETPATH 193Sets the 194.Ev PATH 195environment variable. 196.It LOGIN_SETPRIORITY 197Sets the priority by 198.Xr setpriority 2 . 199.It LOGIN_SETRESOURCES 200Sets the various system resources by 201.Xr setrlimit 2 . 202.It LOGIN_SETUMASK 203Sets the umask by 204.Xr umask 2 . 205.It LOGIN_SETUSER 206Sets the user id to 207.Ar uid 208by 209.Xr setuid 2 . 210.It LOGIN_SETENV 211Sets the environment variables as defined by the setenv keyword, by 212.Xr setenv 3 . 213.It LOGIN_SETALL 214Sets all of the above. 215.El 216.Sh SEE ALSO 217.Xr setlogin 2 , 218.Xr setpriority 2 , 219.Xr setrlimit 2 , 220.Xr setuid 2 , 221.Xr umask 2 , 222.Xr initgroups 3 , 223.Xr secure_path 3 , 224.Xr login.conf 5 225.Sh HISTORY 226The 227.Nm 228family of functions are largely based on the 229.Bsx 230implementation of same, and appeared in 231.Nx 1.5 232by kind permission. 233