library_25.html

Linux程序员的工作手册

registered users.  The database itself is kept in the file
<TT>`/etc/passwd'</TT> on most systems, but on some systems a special
network server gives access to it.
<P>
<H3><A NAME="SEC442" HREF="library_toc.html#SEC442" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC442">The Data Structure that Describes a User</A></H3>
<P>
The functions and data structures for accessing the system user database
are declared in the header file <TT>`pwd.h'</TT>.
<A NAME="IDX1821"></A>
<P>
<A NAME="IDX1822"></A>
<U>Data Type:</U> <B>struct passwd</B><P>
The <CODE>passwd</CODE> data structure is used to hold information about 
entries in the system user data base.  It has at least the following members:
<P>
<DL COMPACT>
<DT><CODE>char *pw_name</CODE>
<DD>The user's login name.
<P>
<DT><CODE>char *pw_passwd.</CODE>
<DD>The encrypted password string.
<P>
<DT><CODE>uid_t pw_uid</CODE>
<DD>The user ID number.
<P>
<DT><CODE>gid_t pw_gid</CODE>
<DD>The user's default group ID number.
<P>
<DT><CODE>char *pw_gecos</CODE>
<DD>A string typically containing the user's real name, and possibly other
information such as a phone number.
<P>
<DT><CODE>char *pw_dir</CODE>
<DD>The user's home directory, or initial working directory.  This might be
a null pointer, in which case the interpretation is system-dependent.
<P>
<DT><CODE>char *pw_shell</CODE>
<DD>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.
</DL>
<P>
<A NAME="IDX1823"></A>
<A NAME="IDX1824"></A>
<H3><A NAME="SEC443" HREF="library_toc.html#SEC443" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC443">Looking Up One User</A></H3>
<P>
You can search the system user database for information about a
specific user using <CODE>getpwuid</CODE> or <CODE>getpwnam</CODE>.  These
functions are declared in <TT>`pwd.h'</TT>.
<P>
<A NAME="IDX1825"></A>
<U>Function:</U> struct passwd * <B>getpwuid</B> <I>(uid_t <VAR>uid</VAR>)</I><P>
This function returns a pointer to a statically-allocated structure
containing information about the user whose user ID is <VAR>uid</VAR>.  This
structure may be overwritten on subsequent calls to <CODE>getpwuid</CODE>.
<P>
A null pointer value indicates there is no user in the data base with
user ID <VAR>uid</VAR>.
<P>
<A NAME="IDX1826"></A>
<U>Function:</U> struct passwd * <B>getpwnam</B> <I>(const char *<VAR>name</VAR>)</I><P>
This function returns a pointer to a statically-allocated structure
containing information about the user whose user name is <VAR>name</VAR>.
This structure may be overwritten on subsequent calls to
<CODE>getpwnam</CODE>.
<P>
A null pointer value indicates there is no user named <VAR>name</VAR>.
<P>
<A NAME="IDX1827"></A>
<H3><A NAME="SEC444" HREF="library_toc.html#SEC444" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC444">Scanning the List of All Users</A></H3>
<P>
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 <TT>`pwd.h'</TT>.
<P>
The recommended way to scan the users is to open the user file and
then call <CODE>fgetpwent</CODE> for each successive user:
<P>
<A NAME="IDX1828"></A>
<U>Function:</U> struct passwd * <B>fgetpwent</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
This function reads the next user entry from <VAR>stream</VAR> and returns a
pointer to the entry.  The structure is statically allocated and is
rewritten on subsequent calls to <CODE>getpwent</CODE>.  You must copy the
contents of the structure if you wish to save the information.
<P>
This stream must correspond to a file in the same format as the standard
password database file.  This function comes from System V.
<P>
Another way to scan all the entries in the group database is with
<CODE>setpwent</CODE>, <CODE>getpwent</CODE>, and <CODE>endpwent</CODE>.  But this method
is less robust than <CODE>fgetpwent</CODE>, so we provide it only for
compatibility with SVID.  In particular, these functions are not
reentrant and are not suitable for use in programs with multiple threads
of control.
<P>
<A NAME="IDX1829"></A>
<U>Function:</U> void <B>setpwent</B> <I>(void)</I><P>
This function initializes a stream which <CODE>getpwent</CODE> uses to read
the user database.
<P>
<A NAME="IDX1830"></A>
<U>Function:</U> struct passwd * <B>getpwent</B> <I>(void)</I><P>
The <CODE>getpwent</CODE> function reads the next entry from the stream
initialized by <CODE>setpwent</CODE>.  It returns a pointer to the entry.  The
structure is statically allocated and is rewritten on subsequent calls
to <CODE>getpwent</CODE>.  You must copy the contents of the structure if you
wish to save the information.
<P>
<A NAME="IDX1831"></A>
<U>Function:</U> void <B>endpwent</B> <I>(void)</I><P>
This function closes the internal stream used by <CODE>getpwent</CODE>.
<P>
<H3><A NAME="SEC445" HREF="library_toc.html#SEC445" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC445">Writing a User Entry</A></H3>
<P>
<A NAME="IDX1832"></A>
<U>Function:</U> int <B>putpwent</B> <I>(const struct passwd *<VAR>p</VAR>, FILE *<VAR>stream</VAR>)</I><P>
This function writes the user entry <CODE>*<VAR>p</VAR></CODE> to the stream
<VAR>stream</VAR>, in the format used for the standard user database
file.  The return value is zero on success and nonzero on failure.
<P>
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</CODE> 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.
<P>
The function <CODE>putpwent</CODE> is declared in <TT>`pwd.h'</TT>.
<P>
<A NAME="IDX1833"></A>
<A NAME="IDX1834"></A>
<H2><A NAME="SEC446" HREF="library_toc.html#SEC446" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC446">Group Database</A></H2>
<P>
This section describes all about how to search and scan the database of
registered groups.  The database itself is kept in the file
<TT>`/etc/group'</TT> on most systems, but on some systems a special network
service provides access to it.
<P>
<H3><A NAME="SEC447" HREF="library_toc.html#SEC447" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC447">The Data Structure for a Group</A></H3>
<P>
The functions and data structures for accessing the system group
database are declared in the header file <TT>`grp.h'</TT>.
<A NAME="IDX1835"></A>
<P>
<A NAME="IDX1836"></A>
<U>Data Type:</U> <B>struct group</B><P>
The <CODE>group</CODE> structure is used to hold information about an entry in
the system group database.  It has at least the following members:
<P>
<DL COMPACT>
<DT><CODE>char *gr_name</CODE>
<DD>The name of the group.
<P>
<DT><CODE>gid_t gr_gid</CODE>
<DD>The group ID of the group.
<P>
<DT><CODE>char **gr_mem</CODE>
<DD>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.
</DL>
<P>
<A NAME="IDX1837"></A>
<A NAME="IDX1838"></A>
<H3><A NAME="SEC448" HREF="library_toc.html#SEC448" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC448">Looking Up One Group</A></H3>
<P>
You can search the group database for information about a specific
group using <CODE>getgrgid</CODE> or <CODE>getgrnam</CODE>.  These functions are
declared in <TT>`grp.h'</TT>.
<P>
<A NAME="IDX1839"></A>
<U>Function:</U> struct group * <B>getgrgid</B> <I>(gid_t <VAR>gid</VAR>)</I><P>
This function returns a pointer to a statically-allocated structure
containing information about the group whose group ID is <VAR>gid</VAR>.
This structure may be overwritten by subsequent calls to
<CODE>getgrgid</CODE>.
<P>
A null pointer indicates there is no group with ID <VAR>gid</VAR>.
<P>
<A NAME="IDX1840"></A>
<U>Function:</U> struct group * <B>getgrnam</B> <I>(const char *<VAR>name</VAR>)</I><P>
This function returns a pointer to a statically-allocated structure
containing information about the group whose group name is <VAR>name</VAR>.
This structure may be overwritten by subsequent calls to
<CODE>getgrnam</CODE>.
<P>
A null pointer indicates there is no group named <VAR>name</VAR>.
<P>
<A NAME="IDX1841"></A>
<H3><A NAME="SEC449" HREF="library_toc.html#SEC449" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC449">Scanning the List of All Groups</A></H3>
<P>
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 <TT>`grp.h'</TT>.
<P>
The recommended way to scan the groups is to open the group file and
then call <CODE>fgetgrent</CODE> for each successive group:
<P>
<A NAME="IDX1842"></A>
<U>Function:</U> struct group * <B>fgetgrent</B> <I>(FILE *<VAR>stream</VAR>)</I><P>
The <CODE>fgetgrent</CODE> function reads the next entry from <VAR>stream</VAR>.
It returns a pointer to the entry.  The structure is statically
allocated and is rewritten on subsequent calls to <CODE>getgrent</CODE>.  You
must copy the contents of the structure if you wish to save the
information.
<P>
The stream must correspond to a file in the same format as the standard
group database file.
<P>
Another way to scan all the entries in the group database is with
<CODE>setgrent</CODE>, <CODE>getgrent</CODE>, and <CODE>endgrent</CODE>.  But this method
is less robust than <CODE>fgetgrent</CODE>, so we provide it only for
compatibility with SVID.  In particular, these functions are not
reentrant and are not suitable for use in programs with multiple threads
of control.
<P>
<A NAME="IDX1843"></A>
<U>Function:</U> void <B>setgrent</B> <I>(void)</I><P>
This function initializes a stream for reading from the group data base.
You use this stream by calling <CODE>getgrent</CODE>.
<P>
<A NAME="IDX1844"></A>
<U>Function:</U> struct group * <B>getgrent</B> <I>(void)</I><P>
The <CODE>getgrent</CODE> function reads the next entry from the stream
initialized by <CODE>setgrent</CODE>.  It returns a pointer to the entry.  The
structure is statically allocated and is rewritten on subsequent calls
to <CODE>getgrent</CODE>.  You must copy the contents of the structure if you
wish to save the information.
<P>
<A NAME="IDX1845"></A>
<U>Function:</U> void <B>endgrent</B> <I>(void)</I><P>
This function closes the internal stream used by <CODE>getgrent</CODE>.
<P>
<H2><A NAME="SEC450" HREF="library_toc.html#SEC450" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC450">User and Group Database Example</A></H2>
<P>
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.
<P>
<PRE>
#include &#60;grp.h&#62;
#include &#60;pwd.h&#62;
#include &#60;sys/types.h&#62;
#include &#60;unistd.h&#62;
#include &#60;stdlib.h&#62;

int
main (void)
{
  uid_t me;
  struct passwd *my_passwd;
  struct group *my_group;
  char **members;

  /* Get information about the user ID.  */
  me = getuid ();
  my_passwd = getpwuid (me);
  if (!my_passwd)
    {
      printf ("Couldn't find out about user %d.\n", (int) me);
      exit (EXIT_FAILURE);
    }

  /* Print the information.  */
  printf ("I am %s.\n", my_passwd-&#62;pw_gecos);
  printf ("My login name is %s.\n", my_passwd-&#62;pw_name);
  printf ("My uid is %d.\n", (int) (my_passwd-&#62;pw_uid));
  printf ("My home directory is %s.\n", my_passwd-&#62;pw_dir);
  printf ("My default shell is %s.\n", my_passwd-&#62;pw_shell);

  /* Get information about the default group ID.  */
  my_group = getgrgid (my_passwd-&#62;pw_gid);
  if (!my_group)
    {
      printf ("Couldn't find out about group %d.\n", (int) my_passwd-&#62;pw_gid);
      exit (EXIT_FAILURE);
    }

  /* Print the information.  */
  printf ("My default group is %s (%d).\n",
	  my_group-&#62;gr_name, (int) (my_passwd-&#62;pw_gid));
  printf ("The members of this group are:\n");
  members = my_group-&#62;gr_mem;
  while (*members)
    {
      printf ("  %s\n", *(members));
      members++;
    }

  return EXIT_SUCCESS;
}
</PRE>
<P>
Here is some output from this program:
<P>
<PRE>
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
</PRE>
<P>Go to the <A HREF="library_24.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_24.html">previous</A>, <A HREF="library_26.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_26.html">next</A> section.<P>