290 lines
6.9 KiB
Groff
290 lines
6.9 KiB
Groff
.\" $NetBSD: login_cap.3,v 1.18 2010/05/05 22:05:31 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 October 6, 2007
|
|
.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_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" "u_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 void
|
|
.Fn login_close "login_cap_t *lc"
|
|
.Ft int
|
|
.Fn setclasscontext "const char *class" "u_int flags"
|
|
.Ft int
|
|
.Fn setusercontext "login_cap_t *lc" "const struct passwd *pwd" "uid_t uid" "u_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
|
|
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.
|