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.24 2024/03/18 08:50:54 op Exp $ 33.\" BSDI $From: login_cap.3,v 1.4 1997/11/07 16:22:27 jch Exp $ 34.\" 35.Dd $Mdocdate: March 18 2024 $ 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.Vt login_cap_t 90pointer is returned. 91.Dv NULL 92is returned if the user class is not found. 93When the 94.Vt 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 , 184.Dv LOGIN_SETRTABLE , 185and 186.Dv LOGIN_SETUMASK 187bits are used 188(see 189.Fn setusercontext 190below). 191It returns 0 on success and \-1 on failure. 192.Pp 193The 194.Fn setusercontext 195function sets the resources according to 196.Ar flags . 197The 198.Ar lc 199argument, if not 200.Dv NULL , 201contains the class information that should be used. 202The 203.Ar pwd 204argument, if not 205.Dv NULL , 206provides information about the user. 207Both 208.Ar lc 209and 210.Ar pwd 211cannot be 212.Dv NULL . 213The 214.Ar uid 215argument is used in place of the user ID contained in the 216.Ar pwd 217structure when calling 218.Xr setuid 2 . 219The 220.Fn setusercontext 221function returns 0 on success and -1 on failure. 222The various bits available to be or-ed together to make up 223.Ar flags 224are: 225.Bl -tag -width LOGIN_SETRESOURCESXX 226.It Dv LOGIN_SETENV 227Sets environment variables specified by the 228.Li setenv 229keyword. 230.It Dv LOGIN_SETGROUP 231Set the group ID and call 232.Xr initgroups 3 233if the 234.Ar pwd 235argument is non-NULL. 236.It Dv LOGIN_SETLOGIN 237Sets the login name using 238.Xr setlogin 2 239if the 240.Ar pwd 241argument is non-NULL. 242.It Dv LOGIN_SETPATH 243Sets the 244.Ev PATH 245environment variable to the value of the 246.Li path 247keyword if specified, or to the value of 248.Dv _PATH_DEFPATH 249in 250.In paths.h 251if not. 252.It Dv LOGIN_SETPRIORITY 253Sets the priority, using 254.Xr setpriority 2 , 255to the value of the 256.Li priority 257keyword if specified, or to 258.Li 0 259if not. 260.It Dv LOGIN_SETRESOURCES 261Sets the various system resources using 262.Xr setrlimit 2 . 263.It Dv LOGIN_SETRTABLE 264Sets the routing table to the value of the 265.Li rtable 266keyword, if specified, 267using 268.Xr setrtable 2 . 269.It Dv LOGIN_SETUMASK 270Sets the umask, using 271.Xr umask 2 , 272to the value of the 273.Li umask 274keyword if specified, or to 275.Li 022 276if not. 277.It Dv LOGIN_SETUSER 278Sets the user ID to 279.Ar uid 280using 281.Xr setuid 2 . 282.It Dv LOGIN_SETALL 283Sets all of the above. 284.El 285.Sh SEE ALSO 286.Xr setlogin 2 , 287.Xr setpriority 2 , 288.Xr setrlimit 2 , 289.Xr setrtable 2 , 290.Xr setuid 2 , 291.Xr umask 2 , 292.Xr initgroups 3 , 293.Xr login.conf 5 294.Sh HISTORY 295The 296.Nm 297function first appeared in 298.Ox 2.8 . 299.Sh CAVEATS 300The string returned by 301.Fn login_getcapstr 302is allocated via 303.Xr malloc 3 304when the specified capability is present and thus it is the responsibility 305of the caller to 306.Fn free 307this space. 308However, if the capability was not found or an error occurred and 309.Fa def 310or 311.Fa err 312(whichever is relevant) are non-NULL the returned value is simply what 313was passed in to 314.Fn login_getcapstr . 315Therefore it is not possible to blindly 316.Fn free 317the return value without first checking it against 318.Fa def 319and 320.Fa err . 321.Pp 322The same warnings set forth in 323.Xr setlogin 2 324apply to 325.Fn setusercontext 326when the 327.Dv LOGIN_SETLOGIN 328flag is used. 329Specifically, changing the login name affects all processes in the current 330session, not just the current process. 331See 332.Xr setlogin 2 333for more information. 334