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