-@node Users and Groups, System Information, Name Service Switch, Top
+@node Users and Groups, System Management, Name Service Switch, Top
@c %MENU% How users are identified and classified
@chapter Users and Groups
@comment sys/types.h
@comment POSIX.1
@deftp {Data Type} uid_t
-This is an integer data type used to represent user IDs. In the GNU
-library, this is an alias for @code{unsigned int}.
+This is an integer data type used to represent user IDs. In
+@theglibc{}, this is an alias for @code{unsigned int}.
@end deftp
@comment sys/types.h
@comment POSIX.1
@deftp {Data Type} gid_t
-This is an integer data type used to represent group IDs. In the GNU
-library, this is an alias for @code{unsigned int}.
+This is an integer data type used to represent group IDs. In
+@theglibc{}, this is an alias for @code{unsigned int}.
@end deftp
@comment unistd.h
@comment unistd.h
@comment POSIX.1
@deftypefun int seteuid (uid_t @var{neweuid})
-This function sets the effective user ID of a process to @var{newuid},
+This function sets the effective user ID of a process to @var{neweuid},
provided that the process is allowed to change its effective user ID. A
privileged process (effective user ID zero) can change its effective
user ID to any legal value. An unprivileged process with a file user ID
@table @code
@item EINVAL
-The value of the @var{newuid} argument is invalid.
+The value of the @var{neweuid} argument is invalid.
@item EPERM
The process may not change to the specified ID.
@comment grp.h
@comment BSD
-@deftypefun int setgroups (size_t @var{count}, gid_t *@var{groups})
+@deftypefun int setgroups (size_t @var{count}, const gid_t *@var{groups})
This function sets the process's supplementary group IDs. It can only
be called from privileged processes. The @var{count} argument specifies
the number of group IDs in the array @var{groups}.
@comment grp.h
@comment BSD
-@deftypefun int initgroups (const char *@var{user}, gid_t @var{gid})
+@deftypefun int initgroups (const char *@var{user}, gid_t @var{group})
The @code{initgroups} function sets the process's supplementary group
-IDs to be the normal default for the user name @var{user}. If @var{gid}
-is not -1, it includes that group also.
+IDs to be the normal default for the user name @var{user}. The group
+@var{group} is automatically included.
This function works by scanning the group database for all the groups
@var{user} belongs to. It then calls @code{setgroups} with the list it
@code{setgroups}.
@end deftypefun
+If you are interested in the groups a particular user belongs to, but do
+not want to change the process's supplementary group IDs, you can use
+@code{getgrouplist}. To use @code{getgrouplist}, your programs should
+include the header file @file{grp.h}.
+@pindex grp.h
+
+@comment grp.h
+@comment BSD
+@deftypefun int getgrouplist (const char *@var{user}, gid_t @var{group}, gid_t *@var{groups}, int *@var{ngroups})
+The @code{getgrouplist} function scans the group database for all the
+groups @var{user} belongs to. Up to *@var{ngroups} group IDs
+corresponding to these groups are stored in the array @var{groups}; the
+return value from the function is the number of group IDs actually
+stored. If *@var{ngroups} is smaller than the total number of groups
+found, then @code{getgrouplist} returns a value of @code{-1} and stores
+the actual number of groups in *@var{ngroups}. The group @var{group} is
+automatically included in the list of groups returned by
+@code{getgrouplist}.
+
+Here's how to use @code{getgrouplist} to read all supplementary groups
+for @var{user}:
+
+@smallexample
+@group
+gid_t *
+supplementary_groups (char *user)
+@{
+ int ngroups = 16;
+ gid_t *groups
+ = (gid_t *) xmalloc (ngroups * sizeof (gid_t));
+ struct passwd *pw = getpwnam (user);
+
+ if (pw == NULL)
+ return NULL;
+
+ if (getgrouplist (pw->pw_name, pw->pw_gid, groups, &ngroups) < 0)
+ @{
+ groups = xrealloc (ngroups * sizeof (gid_t));
+ getgrouplist (pw->pw_name, pw->pw_gid, groups, &ngroups);
+ @}
+ return groups;
+@}
+@end group
+@end smallexample
+@end deftypefun
+
@node Enable/Disable Setuid
@section Enabling and Disabling Setuid Access
@smallexample
#ifdef _POSIX_SAVED_IDS
- setuid (user_user_id);
+ seteuid (user_user_id);
#else
setreuid (geteuid (), getuid ());
#endif
@deftp {Data Type} {struct utmp}
The @code{utmp} data structure is used to hold information about entries
-in the user accounting database. On the GNU system it has the following
+in the user accounting database. On @gnusystems{} it has the following
members:
@table @code
All the @code{get*} functions mentioned before store the information
they return in a static buffer. This can be a problem in multi-threaded
-programs since the data return for the request is overwritten be the
-return value data in another thread. Therefore the GNU C Library
+programs since the data returned for the request is overwritten by the
+return value data in another thread. Therefore @theglibc{}
provides as extensions three more functions which return the data in a
user-provided buffer.
database can be successfully opened.
@end deftypefun
-Specially for maintaining log-like databases the GNU C Library provides
+Specially for maintaining log-like databases @theglibc{} provides
the following function:
@comment utmp.h
subset of these functions, they are not standardized. There are often
subtle differences in the return types, and there are considerable
differences between the various definitions of @code{struct utmp}. When
-programming for the GNU system, it is probably best to stick
+programming for @theglibc{}, it is probably best to stick
with the functions described in this section. If however, you want your
program to be portable, consider using the XPG functions described in
@ref{XPG Functions}, or take a look at the BSD compatible functions in
the time when the system clock changed, and for entries of type
@code{NEW_TIME} this is the time the system clock was set to.
@end table
-On the GNU system, @code{struct utmpx} is identical to @code{struct
+In @theglibc{}, @code{struct utmpx} is identical to @code{struct
utmp} except for the fact that including @file{utmpx.h} does not make
visible the declaration of @code{struct exit_status}.
@end deftp
The following macros are defined for use as values for the
@code{ut_type} member of the @code{utmpx} structure. The values are
-integer constants and are, on the GNU system, identical to the
+integer constants and are, in @theglibc{}, identical to the
definitions in @file{utmp.h}.
@table @code
@comment utmpx.h
@comment XPG4.2
@deftypefun void setutxent (void)
-This function is similar to @code{setutent}. On the GNU system it is
+This function is similar to @code{setutent}. In @theglibc{} it is
simply an alias for @code{setutent}.
@end deftypefun
@comment XPG4.2
@deftypefun {struct utmpx *} getutxent (void)
The @code{getutxent} function is similar to @code{getutent}, but returns
-a pointer to a @code{struct utmpx} instead of @code{struct utmp}. On
-the GNU system it simply is an alias for @code{getutent}.
+a pointer to a @code{struct utmpx} instead of @code{struct utmp}. In
+@theglibc{} it simply is an alias for @code{getutent}.
@end deftypefun
@comment utmpx.h
@comment XPG4.2
@deftypefun void endutxent (void)
-This function is similar to @code{endutent}. On the GNU system it is
+This function is similar to @code{endutent}. In @theglibc{} it is
simply an alias for @code{endutent}.
@end deftypefun
@comment XPG4.2
@deftypefun {struct utmpx *} getutxid (const struct utmpx *@var{id})
This function is similar to @code{getutid}, but uses @code{struct utmpx}
-instead of @code{struct utmp}. On the GNU system it is simply an alias
+instead of @code{struct utmp}. In @theglibc{} it is simply an alias
for @code{getutid}.
@end deftypefun
@comment XPG4.2
@deftypefun {struct utmpx *} getutxline (const struct utmpx *@var{line})
This function is similar to @code{getutid}, but uses @code{struct utmpx}
-instead of @code{struct utmp}. On the GNU system it is simply an alias
+instead of @code{struct utmp}. In @theglibc{} it is simply an alias
for @code{getutline}.
@end deftypefun
@comment utmpx.h
@comment XPG4.2
@deftypefun {struct utmpx *} pututxline (const struct utmpx *@var{utmp})
-The @code{pututxline} function provides functionality identical to
+The @code{pututxline} function is functionally identical to
@code{pututline}, but uses @code{struct utmpx} instead of @code{struct
-utmp}. On the GNU system @code{pututxline} is simply an alias for
+utmp}. In @theglibc{}, @code{pututxline} is simply an alias for
@code{pututline}.
@end deftypefun
+@comment utmpx.h
+@comment XPG4.2
+@deftypefun int utmpxname (const char *@var{file})
+The @code{utmpxname} function is functionally identical to
+@code{utmpname}. In @theglibc{}, @code{utmpxname} is simply an
+alias for @code{utmpname}.
+@end deftypefun
+
+You can translate between a traditional @code{struct utmp} and an XPG
+@code{struct utmpx} with the following functions. In @theglibc{},
+these functions are merely copies, since the two structures are
+identical.
+
+@comment utmpx.h
+@comment utmp.h
+@comment GNU
+@deftypefun int getutmp (const struct utmpx *@var{utmpx}, struct utmp *@var{utmp})
+@code{getutmp} copies the information, insofar as the structures are
+compatible, from @var{utmpx} to @var{utmp}.
+@end deftypefun
+
+@comment utmpx.h
+@comment utmp.h
+@comment GNU
+@deftypefun int getutmpx (const struct utmp *@var{utmp}, struct utmpx *@var{utmpx})
+@code{getutmpx} copies the information, insofar as the structures are
+compatible, from @var{utmp} to @var{utmpx}.
+@end deftypefun
+
@node Logging In and Out
@subsection Logging In and Out
If a user with ID @var{uid} is found, the pointer returned in
@var{result} points to the record which contains the wanted data (i.e.,
@var{result} contains the value @var{result_buf}). If no user is found
-or if an error occured, the pointer returned in @var{result} is a null
+or if an error occurred, the pointer returned in @var{result} is a null
pointer. The function returns zero or an error code. If the buffer
@var{buffer} is too small to contain all the needed information, the
error code @code{ERANGE} is returned and @var{errno} is set to
@comment pwd.h
@comment GNU
-@deftypefun int getpwent_r (struct passwd *@var{result_buf}, char *@var{buffer}, int @var{buflen}, struct passwd **@var{result})
+@deftypefun int getpwent_r (struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
This function is similar to @code{getpwent} in that it returns the next
entry from the stream initialized by @code{setpwent}. Like
@code{fgetpwent_r}, it uses the user-supplied buffers in
would inevitably leave out much of the important information.
@c Then how are programmers to modify the password file? -zw
+The group and user ID fields are left empty if the group or user name
+starts with a - or +.
+
The function @code{putpwent} is declared in @file{pwd.h}.
@end deftypefun
If a group with ID @var{gid} is found, the pointer returned in
@var{result} points to the record which contains the wanted data (i.e.,
@var{result} contains the value @var{result_buf}). If no group is found
-or if an error occured, the pointer returned in @var{result} is a null
+or if an error occurred, the pointer returned in @var{result} is a null
pointer. The function returns zero or an error code. If the buffer
@var{buffer} is too small to contain all the needed information, the
error code @code{ERANGE} is returned and @var{errno} is set to
host names is not supported so far.
In Sun Microsystems SunOS appeared a new kind of database, the netgroup
-database. It allows to group hosts, users, and domain freely, giving
-them individual names. More concrete: a netgroup is a list of triples
-consisting of a host name, a user name, and a domain name, where any of
-the entries can be a wildcard entry, matching all inputs. A last
+database. It allows grouping hosts, users, and domains freely, giving
+them individual names. To be more concrete, a netgroup is a list of triples
+consisting of a host name, a user name, and a domain name where any of
+the entries can be a wildcard entry matching all inputs. A last
possibility is that names of other netgroups can also be given in the
list specifying a netgroup. So one can construct arbitrary hierarchies
without loops.
Sun's implementation allows netgroups only for the @code{nis} or
-@code{nisplus} service @pxref{Services in the NSS configuration}. The
-implementation in the GNU C library has no such restriction. An entry
+@code{nisplus} service, @pxref{Services in the NSS configuration}. The
+implementation in @theglibc{} has no such restriction. An entry
in either of the input services must have the following form:
@smallexample
Any of the fields in the triple can be empty which means anything
matches. While describing the functions we will see that the opposite
case is useful as well. I.e., there may be entries which will not
-match any input. For entries like a name consisting of the single
+match any input. For entries like this, a name consisting of the single
character @code{-} shall be used.
@node Lookup Netgroup
@comment BSD
@deftypefun int setnetgrent (const char *@var{netgroup})
A call to this function initializes the internal state of the library to
-allow following calls of the @code{getnetgrent} iterate over all entries
+allow following calls of the @code{getnetgrent} to iterate over all entries
in the netgroup with name @var{netgroup}.
-When the call is successful (i.e., when a netgroup with this name exist)
+When the call is successful (i.e., when a netgroup with this name exists)
the return value is @code{1}. When the return value is @code{0} no
netgroup of this name is known or some other error occurred.
@end deftypefun
@comment BSD
@deftypefun int getnetgrent (char **@var{hostp}, char **@var{userp}, char **@var{domainp})
This function returns the next unprocessed entry of the currently
-selected netgroup. The string pointers, which addresses are passed in
+selected netgroup. The string pointers, in which addresses are passed in
the arguments @var{hostp}, @var{userp}, and @var{domainp}, will contain
after a successful call pointers to appropriate strings. If the string
in the next entry is empty the pointer has the value @code{NULL}.
-The returned string pointers are only valid unless no of the netgroup
+The returned string pointers are only valid if none of the netgroup
related functions are called.
The return value is @code{1} if the next entry was successfully read. A
@comment netdb.h
@comment GNU
-@deftypefun int getnetgrent_r (char **@var{hostp}, char **@var{userp}, char **@var{domainp}, char *@var{buffer}, int @var{buflen})
+@deftypefun int getnetgrent_r (char **@var{hostp}, char **@var{userp}, char **@var{domainp}, char *@var{buffer}, size_t @var{buflen})
This function is similar to @code{getnetgrent} with only one exception:
the strings the three string pointers @var{hostp}, @var{userp}, and
@var{domainp} point to, are placed in the buffer of @var{buflen} bytes
@comment netdb.h
@comment BSD
@deftypefun void endnetgrent (void)
-This function free all buffers which were allocated to process the last
+This function frees all buffers which were allocated to process the last
selected netgroup. As a result all string pointers returned by calls
to @code{getnetgrent} are invalid afterwards.
@end deftypefun
@end enumerate
Any of the pointers @var{hostp}, @var{userp}, and @var{domainp} can be
-@code{NULL} which means any value is excepted in this position. This is
+@code{NULL} which means any value is accepted in this position. This is
also true for the name @code{-} which should not match any other string
otherwise.
git://sourceware.org / glibc.git / blobdiff