1.\" $NetBSD: login_cap.3,v 1.21 2013/06/23 08:38:41 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 June 20, 2013 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_getpwclass , 46.Nm login_close , 47.Nm setclasscontext , 48.Nm setusercontext 49.Nd query login.conf database about a user class 50.Sh LIBRARY 51.Lb libutil 52.Sh SYNOPSIS 53.In sys/types.h 54.In login_cap.h 55.Ft login_cap_t * 56.Fn login_getclass "char *class" 57.Ft int 58.Fn login_getcapbool "login_cap_t *lc" "const char *cap" "u_int def" 59.Ft quad_t 60.Fn login_getcapnum "login_cap_t *lc" "const char *cap" "quad_t def" "quad_t err" 61.Ft quad_t 62.Fn login_getcapsize "login_cap_t *lc" "const char *cap" "quad_t def" "quad_t err" 63.Ft char * 64.Fn login_getcapstr "login_cap_t *lc" "const char *cap" "char *def" "char *err" 65.Ft quad_t 66.Fn login_getcaptime "login_cap_t *lc" "const char *cap" "quad_t def" "quad_t err" 67.Ft login_cap_t * 68.Fn login_getpwclass "struct passwd *pwd" 69.Ft void 70.Fn login_close "login_cap_t *lc" 71.Ft int 72.Fn setclasscontext "const char *class" "u_int flags" 73.Ft int 74.Fn setusercontext "login_cap_t *lc" "const struct passwd *pwd" "uid_t uid" "u_int flags" 75.Sh DESCRIPTION 76The 77.Fn login_getclass 78function extracts the entry specified by 79.Ar class 80(or 81.Li default 82if 83.Ar class 84is 85.Dv NULL 86or the empty string) 87from 88.Pa /etc/login.conf 89(see 90.Xr login.conf 5 ) . 91If the entry is found, a 92.Li login_cap_t 93pointer is returned. 94.Dv NULL 95is returned if the user class is not found. 96When the 97.Li login_cap_t 98structure is no longer needed, it should be freed by the 99.Fn login_close 100function. 101.Pp 102The 103.Fn login_getpwclass 104function is equivalent to: 105.Dl login_getclass(pwd\ ? pwd->pw_class\ : NULL) 106.Pp 107Once 108.Ar lc 109has been returned by 110.Fn login_getclass , 111any of the other 112.Fn login_* 113functions may be called. 114.Pp 115The 116.Fn login_getcapnum , 117.Fn login_getcapsize , 118.Fn login_getcapstr , 119and 120.Fn login_getcaptime 121functions all query the database entry for a field named 122.Ar cap . 123If the field is found, its value is returned. 124If the field is not found, the value specified by 125.Ar def 126is returned. 127If an error is encountered while trying to find the field, 128.Ar err 129is returned. 130See 131.Xr login.conf 5 132for a discussion of the various textual forms the value may take. 133The 134.Fn login_getcapbool 135function is slightly different. 136It returns 137.Ar def 138if no capabilities were found for this class (typically meaning that 139the default class was used and the 140.Li /etc/login.conf 141file is missing). 142It returns a non-zero value if 143.Ar cap , 144with no value, was found, 145zero otherwise. 146.Pp 147The 148.Fn setclasscontext 149function takes 150.Ar class , 151the name of a user class, 152and sets the resources defined by that class according to 153.Ar flags . 154Only the 155.Dv LOGIN_SETPATH , 156.Dv LOGIN_SETPRIORITY , 157.Dv LOGIN_SETRESOURCES , 158and 159.Dv LOGIN_SETUMASK 160bits are used. 161(See 162.Fn setusercontext 163below). 164It returns 0 on success and -1 on failure. 165.Pp 166The 167.Fn setusercontext 168function 169sets the resources according to 170.Ar flags . 171The 172.Ar lc 173argument, if not 174.Dv NULL , 175contains the class information that should 176be used. 177The 178.Ar pwd 179argument, if not 180.Dv NULL , 181provides information about the user. 182Both 183.Ar lc 184and 185.Ar pwd 186cannot be 187.Dv NULL . 188The 189.Ar uid 190argument is used in place of the user id contained in the 191.Ar pwd 192structure when calling 193.Xr setuid 2 . 194The various bits available to be or-ed together to make up 195.Ar flags 196are: 197.Bl -tag -width LOGIN_SETRESOURCESXX 198.It LOGIN_SETGID 199Set the group id. 200Requires the 201.Ar pwd 202field be specified. 203.It LOGIN_SETGROUPS 204Set the group membership list by calling 205.Xr initgroups 3 . 206Requires the 207.Ar pwd 208field be specified. 209.It LOGIN_SETGROUP 210Set the group id and call 211.Xr initgroups 3 . 212Requires the 213.Ar pwd 214field be specified. 215.It LOGIN_SETLOGIN 216Sets the login name by 217.Xr setlogin 2 . 218Requires the 219.Ar pwd 220field be specified. 221.It LOGIN_SETPATH 222Sets the 223.Ev PATH 224environment variable. 225.It LOGIN_SETPRIORITY 226Sets the priority by 227.Xr setpriority 2 . 228.It LOGIN_SETRESOURCES 229Sets the various system resources by 230.Xr setrlimit 2 . 231.It LOGIN_SETUMASK 232Sets the umask by 233.Xr umask 2 . 234.It LOGIN_SETUSER 235Sets the user id to 236.Ar uid 237by 238.Xr setuid 2 . 239.It LOGIN_SETENV 240Sets the environment variables as defined by the setenv keyword, by 241.Xr setenv 3 . 242.It LOGIN_SETALL 243Sets all of the above. 244.El 245.Sh SEE ALSO 246.Xr setlogin 2 , 247.Xr setpriority 2 , 248.Xr setrlimit 2 , 249.Xr setuid 2 , 250.Xr umask 2 , 251.Xr initgroups 3 , 252.Xr secure_path 3 , 253.Xr login.conf 5 254.Sh HISTORY 255The 256.Nm 257family of functions are largely based on the 258.Bsx 259implementation of same, and appeared in 260.Nx 1.5 261by kind permission. 262.Sh CAVEATS 263The string returned by 264.Fn login_getcapstr 265is allocated via 266.Xr malloc 3 267when the specified capability is present and thus it is the responsibility 268of the caller to 269.Fn free 270this space. 271However, if the capability was not found or an error occurred and 272.Fa def 273or 274.Fa err 275(whichever is relevant) are 276.Pf non- Dv NULL 277the returned value is simply what was passed in to 278.Fn login_getcapstr . 279Therefore it is not possible to blindly 280.Fn free 281the return value without first checking it against 282.Fa def 283and 284.Fa err . 285.Pp 286The same warnings set forth in 287.Xr setlogin 2 288apply to 289.Fn setusercontext 290when the 291.Dv LOGIN_SETLOGIN 292flag is used. 293Specifically, changing the login name affects all processes in the current 294session, not just the current process. 295See 296.Xr setlogin 2 297for more information. 298