lib/libutil/login_cap.3

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