users.texi

一个C源代码分析器

@comment stdio.h
@comment POSIX.1
@deftypefun {char *} cuserid (char *@var{string})
The @code{cuserid} function returns a pointer to a string containing a
user name associated with the effective ID of the process.  If
@var{string} is not a null pointer, it should be an array that can hold
at least @code{L_cuserid} characters; the string is returned in this
array.  Otherwise, a pointer to a string in a static area is returned.
This string is statically allocated and might be overwritten on
subsequent calls to this function or to @code{getlogin}.
@end deftypefun

@comment stdio.h
@comment POSIX.1
@deftypevr Macro int L_cuserid
An integer constant that indicates how long an array you might need to
store a user name.
@end deftypevr

These functions let your program identify positively the user who is
running or the user who logged in this session.  (These can differ when
setuid programs are involved; @xref{Process Persona}.)  The user cannot
do anything to fool these functions.

For most purposes, it is more useful to use the environment variable
@code{LOGNAME} to find out who the user is.  This is more flexible
precisely because the user can set @code{LOGNAME} arbitrarily.
@xref{Standard Environment}.

@node User Database
@section User Database
@cindex user database
@cindex password database
@pindex /etc/passwd

This section describes all about how to search and scan the database of
registered users.  The database itself is kept in the file
@file{/etc/passwd} on most systems, but on some systems a special
network server gives access to it.

@menu
* User Data Structure::         What each user record contains.
* Lookup User::                 How to look for a particular user.
* Scanning All Users::          Scanning the list of all users, one by one.
* Writing a User Entry::        How a program can rewrite a user's record.
@end menu

@node User Data Structure
@subsection The Data Structure that Describes a User

The functions and data structures for accessing the system user database
are declared in the header file @file{pwd.h}.
@pindex pwd.h

@comment pwd.h
@comment POSIX.1
@deftp {Data Type} {struct passwd}
The @code{passwd} data structure is used to hold information about 
entries in the system user data base.  It has at least the following members:

@table @code
@item char *pw_name
The user's login name.

@item char *pw_passwd.
The encrypted password string.

@item uid_t pw_uid
The user ID number.

@item gid_t pw_gid
The user's default group ID number.

@item char *pw_gecos
A string typically containing the user's real name, and possibly other
information such as a phone number.

@item char *pw_dir
The user's home directory, or initial working directory.  This might be
a null pointer, in which case the interpretation is system-dependent.

@item char *pw_shell
The user's default shell, or the initial program run when the user logs in.
This might be a null pointer, indicating that the system default should
be used.
@end table
@end deftp

@node Lookup User
@subsection Looking Up One User
@cindex converting user ID to user name
@cindex converting user name to user ID

You can search the system user database for information about a
specific user using @code{getpwuid} or @code{getpwnam}.  These
functions are declared in @file{pwd.h}.

@comment pwd.h
@comment POSIX.1
@deftypefun {struct passwd *} getpwuid (uid_t @var{uid})
This function returns a pointer to a statically-allocated structure
containing information about the user whose user ID is @var{uid}.  This
structure may be overwritten on subsequent calls to @code{getpwuid}.

A null pointer value indicates there is no user in the data base with
user ID @var{uid}.
@end deftypefun

@comment pwd.h
@comment POSIX.1
@deftypefun {struct passwd *} getpwnam (const char *@var{name})
This function returns a pointer to a statically-allocated structure
containing information about the user whose user name is @var{name}.
This structure may be overwritten on subsequent calls to
@code{getpwnam}.

A null pointer value indicates there is no user named @var{name}.
@end deftypefun

@node Scanning All Users
@subsection Scanning the List of All Users
@cindex scanning the user list

This section explains how a program can read the list of all users in
the system, one user at a time.  The functions described here are
declared in @file{pwd.h}.

You can use the @code{fgetpwent} function to read user entries from a
particular file.

@comment pwd.h
@comment SVID
@deftypefun {struct passwd *} fgetpwent (FILE *@var{stream})
This function reads the next user entry from @var{stream} and returns a
pointer to the entry.  The structure is statically allocated and is
rewritten on subsequent calls to @code{fgetpwent}.  You must copy the
contents of the structure if you wish to save the information.

This stream must correspond to a file in the same format as the standard
password database file.  This function comes from System V.
@end deftypefun

The way to scan all the entries in the user database is with
@code{setpwent}, @code{getpwent}, and @code{endpwent}.

@comment pwd.h
@comment SVID, BSD
@deftypefun void setpwent (void)
This function initializes a stream which @code{getpwent} uses to read
the user database.
@end deftypefun

@comment pwd.h
@comment POSIX.1
@deftypefun {struct passwd *} getpwent (void)
The @code{getpwent} function reads the next entry from the stream
initialized by @code{setpwent}.  It returns a pointer to the entry.  The
structure is statically allocated and is rewritten on subsequent calls
to @code{getpwent}.  You must copy the contents of the structure if you
wish to save the information.
@end deftypefun

@comment pwd.h
@comment SVID, BSD
@deftypefun void endpwent (void)
This function closes the internal stream used by @code{getpwent}.
@end deftypefun

@node Writing a User Entry
@subsection Writing a User Entry

@comment pwd.h
@comment SVID
@deftypefun int putpwent (const struct passwd *@var{p}, FILE *@var{stream})
This function writes the user entry @code{*@var{p}} to the stream
@var{stream}, in the format used for the standard user database
file.  The return value is zero on success and nonzero on failure.

This function exists for compatibility with SVID.  We recommend that you
avoid using it, because it makes sense only on the assumption that the
@code{struct passwd} structure has no members except the standard ones;
on a system which merges the traditional Unix data base with other
extended information about users, adding an entry using this function
would inevitably leave out much of the important information.

The function @code{putpwent} is declared in @file{pwd.h}.
@end deftypefun

@node Group Database
@section Group Database
@cindex group database
@pindex /etc/group

This section describes all about how to search and scan the database of
registered groups.  The database itself is kept in the file
@file{/etc/group} on most systems, but on some systems a special network
service provides access to it.

@menu
* Group Data Structure::        What each group record contains.
* Lookup Group::                How to look for a particular group.
* Scanning All Groups::         Scanning the list of all groups.
@end menu

@node Group Data Structure
@subsection The Data Structure for a Group

The functions and data structures for accessing the system group
database are declared in the header file @file{grp.h}.
@pindex grp.h

@comment grp.h
@comment POSIX.1
@deftp {Data Type} {struct group} 
The @code{group} structure is used to hold information about an entry in
the system group database.  It has at least the following members:

@table @code
@item char *gr_name
The name of the group.

@item gid_t gr_gid
The group ID of the group.

@item char **gr_mem
A vector of pointers to the names of users in the group.  Each user name
is a null-terminated string, and the vector itself is terminated by a
null pointer.
@end table
@end deftp

@node Lookup Group
@subsection Looking Up One Group
@cindex converting group name to group ID
@cindex converting group ID to group name

You can search the group database for information about a specific
group using @code{getgrgid} or @code{getgrnam}.  These functions are
declared in @file{grp.h}.

@comment grp.h
@comment POSIX.1
@deftypefun {struct group *} getgrgid (gid_t @var{gid})
This function returns a pointer to a statically-allocated structure
containing information about the group whose group ID is @var{gid}.
This structure may be overwritten by subsequent calls to
@code{getgrgid}.

A null pointer indicates there is no group with ID @var{gid}.
@end deftypefun

@comment grp.h
@comment SVID, BSD
@deftypefun {struct group *} getgrnam (const char *@var{name})
This function returns a pointer to a statically-allocated structure
containing information about the group whose group name is @var{name}.
This structure may be overwritten by subsequent calls to
@code{getgrnam}.

A null pointer indicates there is no group named @var{name}.
@end deftypefun

@node Scanning All Groups
@subsection Scanning the List of All Groups
@cindex scanning the group list

This section explains how a program can read the list of all groups in
the system, one group at a time.  The functions described here are
declared in @file{grp.h}.

You can use the @code{fgetgrent} function to read group entries from a
particular file.

@comment grp.h
@comment SVID
@deftypefun {struct group *} fgetgrent (FILE *@var{stream})
The @code{fgetgrent} function reads the next entry from @var{stream}.
It returns a pointer to the entry.  The structure is statically
allocated and is rewritten on subsequent calls to @code{fgetgrent}.  You
must copy the contents of the structure if you wish to save the
information.

The stream must correspond to a file in the same format as the standard
group database file.
@end deftypefun

The way to scan all the entries in the group database is with
@code{setgrent}, @code{getgrent}, and @code{endgrent}.

@comment grp.h
@comment SVID, BSD
@deftypefun void setgrent (void)
This function initializes a stream for reading from the group data base.
You use this stream by calling @code{getgrent}.
@end deftypefun

@comment grp.h
@comment SVID, BSD
@deftypefun {struct group *} getgrent (void)
The @code{getgrent} function reads the next entry from the stream
initialized by @code{setgrent}.  It returns a pointer to the entry.  The
structure is statically allocated and is rewritten on subsequent calls
to @code{getgrent}.  You must copy the contents of the structure if you
wish to save the information.
@end deftypefun

@comment grp.h
@comment SVID, BSD
@deftypefun void endgrent (void)
This function closes the internal stream used by @code{getgrent}.
@end deftypefun

@node Database Example
@section User and Group Database Example

Here is an example program showing the use of the system database inquiry
functions.  The program prints some information about the user running
the program.

@smallexample
@include db.c.texi
@end smallexample

Here is some output from this program:

@smallexample
I am Throckmorton Snurd.
My login name is snurd.
My uid is 31093.
My home directory is /home/fsg/snurd.
My default shell is /bin/sh.
My default group is guest (12).
The members of this group are:
  friedman
  tami
@end smallexample