.\" $NetBSD: login_cap.3,v 1.23 2016/01/23 07:21:18 wiz Exp $
.\"
.\" Copyright (c) 1996,1997 Berkeley Software Design, Inc. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by Berkeley Software Design,
.\"	Inc.
.\" 4. The name of Berkeley Software Design, Inc.  may not be used to endorse
.\"    or promote products derived from this software without specific prior
.\"    written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN, INC. ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL BERKELEY SOFTWARE DESIGN, INC. BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" BSDI login_cap.3,v 1.4 1997/11/07 16:22:27 jch Exp
.\"
.Dd June 20, 2013
.Dt LOGIN_CAP 3
.Os
.Sh NAME
.Nm login_getclass ,
.Nm login_getcapbool ,
.Nm login_getcapnum ,
.Nm login_getcapsize ,
.Nm login_getcapstr ,
.Nm login_getcaptime ,
.Nm login_getpwclass ,
.Nm login_close ,
.Nm setclasscontext ,
.Nm setusercontext
.Nd query login.conf database about a user class
.Sh LIBRARY
.Lb libutil
.Sh SYNOPSIS
.In sys/types.h
.In login_cap.h
.Ft login_cap_t *
.Fn login_getclass "char *class"
.Ft int
.Fn login_getcapbool "login_cap_t *lc" "const char *cap" "unsigned int def"
.Ft quad_t
.Fn login_getcapnum "login_cap_t *lc" "const char *cap" "quad_t def" "quad_t err"
.Ft quad_t
.Fn login_getcapsize "login_cap_t *lc" "const char *cap" "quad_t def" "quad_t err"
.Ft char *
.Fn login_getcapstr "login_cap_t *lc" "const char *cap" "char *def" "char *err"
.Ft quad_t
.Fn login_getcaptime "login_cap_t *lc" "const char *cap" "quad_t def" "quad_t err"
.Ft login_cap_t *
.Fn login_getpwclass "struct passwd *pwd"
.Ft void
.Fn login_close "login_cap_t *lc"
.Ft int
.Fn setclasscontext "const char *class" "unsigned int flags"
.Ft int
.Fn setusercontext "login_cap_t *lc" "const struct passwd *pwd" "uid_t uid" "unsigned int flags"
.Sh DESCRIPTION
The
.Fn login_getclass
function extracts the entry specified by
.Ar class
(or
.Li default
if
.Ar class
is
.Dv NULL
or the empty string)
from
.Pa /etc/login.conf
(see
.Xr login.conf 5 ) .
If the entry is found, a
.Li login_cap_t
pointer is returned.
.Dv NULL
is returned if the user class is not found.
When the
.Li login_cap_t
structure is no longer needed, it should be freed by the
.Fn login_close
function.
.Pp
The
.Fn login_getpwclass
function is equivalent to:
.Dl login_getclass(pwd\ ? pwd->pw_class\ : NULL)
.Pp
Once
.Ar lc
has been returned by
.Fn login_getclass ,
any of the other
.Fn login_*
functions may be called.
.Pp
The
.Fn login_getcapnum ,
.Fn login_getcapsize ,
.Fn login_getcapstr ,
and
.Fn login_getcaptime
functions all query the database entry for a field named
.Ar cap .
If the field is found, its value is returned.
If the field is not found, the value specified by
.Ar def
is returned.
If an error is encountered while trying to find the field,
.Ar err
is returned.
See
.Xr login.conf 5
for a discussion of the various textual forms the value may take.
The
.Fn login_getcapbool
function is slightly different.
It returns
.Ar def
if no capabilities were found for this class (typically meaning that
the default class was used and the
.Li /etc/login.conf
file is missing).
It returns a non-zero value if
.Ar cap ,
with no value, was found,
zero otherwise.
.Pp
The
.Fn setclasscontext
function takes
.Ar class ,
the name of a user class,
and sets the resources defined by that class according to
.Ar flags .
Only the
.Dv LOGIN_SETPATH ,
.Dv LOGIN_SETPRIORITY ,
.Dv LOGIN_SETRESOURCES ,
and
.Dv LOGIN_SETUMASK
bits are used.
(See
.Fn setusercontext
below).
It returns 0 on success and -1 on failure.
.Pp
The
.Fn setusercontext
function
sets the resources according to
.Ar flags .
The
.Ar lc
argument, if not
.Dv NULL ,
contains the class information that should
be used.
The
.Ar pwd
argument, if not
.Dv NULL ,
provides information about the user.
Both
.Ar lc
and
.Ar pwd
cannot be
.Dv NULL .
The
.Ar uid
argument is used in place of the user id contained in the
.Ar pwd
structure when calling
.Xr setuid 2 .
The various bits available to be or-ed together to make up
.Ar flags
are:
.Bl -tag -width LOGIN_SETRESOURCESXX
.It LOGIN_SETGID
Set the group id.
Requires the
.Ar pwd
field be specified.
.It LOGIN_SETGROUPS
Set the group membership list by calling
.Xr initgroups 3 .
Requires the
.Ar pwd
field be specified.
.It LOGIN_SETGROUP
Set the group id and call
.Xr initgroups 3 .
Requires the
.Ar pwd
field be specified.
.It LOGIN_SETLOGIN
Sets the login name by
.Xr setlogin 2 .
Requires the
.Ar pwd
field be specified.
.It LOGIN_SETPATH
Sets the
.Ev PATH
environment variable.
.It LOGIN_SETPRIORITY
Sets the priority by
.Xr setpriority 2 .
.It LOGIN_SETRESOURCES
Sets the various system resources by
.Xr setrlimit 2 .
.It LOGIN_SETUMASK
Sets the umask by
.Xr umask 2 .
.It LOGIN_SETUSER
Sets the user id to
.Ar uid
by
.Xr setuid 2 .
.It LOGIN_SETENV
Sets the environment variables as defined by the setenv keyword, by
.Xr setenv 3 .
.It LOGIN_SETALL
Sets all of the above.
.El
.Sh SEE ALSO
.Xr setlogin 2 ,
.Xr setpriority 2 ,
.Xr setrlimit 2 ,
.Xr setuid 2 ,
.Xr umask 2 ,
.Xr initgroups 3 ,
.Xr secure_path 3 ,
.Xr login.conf 5
.Sh HISTORY
The
.Nm
family of functions are largely based on the
.Bsx
implementation of same, and appeared in
.Nx 1.5
by kind permission.
.Sh CAVEATS
The string returned by
.Fn login_getcapstr
is allocated via
.Xr malloc 3
when the specified capability is present and thus it is the responsibility
of the caller to
.Fn free
this space.
However, if the capability was not found or an error occurred and
.Fa def
or
.Fa err
(whichever is relevant) are
.Pf non- Dv NULL
the returned value is simply what was passed in to
.Fn login_getcapstr .
Therefore it is not possible to blindly
.Fn free
the return value without first checking it against
.Fa def
and
.Fa err .
.Pp
The same warnings set forth in
.Xr setlogin 2
apply to
.Fn setusercontext
when the
.Dv LOGIN_SETLOGIN
flag is used.
Specifically, changing the login name affects all processes in the current
session, not just the current process.
See
.Xr setlogin 2
for more information.