man3/fgetpwent.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   8 .\"     386BSD man pages
   9 .\"
  10 .\" Modified Sat Jul 24 19:37:37 1993 by Rik Faith (faith@cs.unc.edu)
  11 .\" Modified Mon May 27 22:40:48 1996 by Martin Schulze (joey@linux.de)
  12 .\"
  13 .TH FGETPWENT 3 2022-09-09 "Linux man-pages (unreleased)"
  14 .SH NAME
  15 fgetpwent \- get password file entry
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <stdio.h>
  22 .B #include <sys/types.h>
  23 .B #include <pwd.h>
  24 .PP
  25 .BI "struct passwd *fgetpwent(FILE *" stream );
  26 .fi
  27 .PP
  28 .RS -4
  29 Feature Test Macro Requirements for glibc (see
  30 .BR feature_test_macros (7)):
  31 .RE
  32 .PP
  33 .BR fgetpwent ():
  34 .nf
  35     Since glibc 2.19:
  36         _DEFAULT_SOURCE
  37     Glibc 2.19 and earlier:
  38         _SVID_SOURCE
  39 .fi
  40 .SH DESCRIPTION
  41 The
  42 .BR fgetpwent ()
  43 function returns a pointer to a structure containing
  44 the broken out fields of a line in the file \fIstream\fP.
  45 The first time it is called it returns the first entry;
  46 thereafter, it returns successive entries.
  47 The file referred to by
  48 .I stream
  49 must have the same format as
  50 .I /etc/passwd
  51 (see
  52 .BR passwd (5)).
  53 .PP
  54 The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows:
  55 .PP
  56 .in +4n
  57 .EX
  58 struct passwd {
  59     char   *pw_name;       /* username */
  60     char   *pw_passwd;     /* user password */
  61     uid_t   pw_uid;        /* user ID */
  62     gid_t   pw_gid;        /* group ID */
  63     char   *pw_gecos;      /* real name */
  64     char   *pw_dir;        /* home directory */
  65     char   *pw_shell;      /* shell program */
  66 };
  67 .EE
  68 .in
  69 .SH RETURN VALUE
  70 The
  71 .BR fgetpwent ()
  72 function returns a pointer to a
  73 .I passwd
  74 structure, or NULL if
  75 there are no more entries or an error occurs.
  76 In the event of an error,
  77 .I errno
  78 is set to indicate the error.
  79 .SH ERRORS
  80 .TP
  81 .B ENOMEM
  82 Insufficient memory to allocate
  83 .I passwd
  84 structure.
  85 .SH FILES
  86 .TP
  87 .I /etc/passwd
  88 password database file
  89 .SH ATTRIBUTES
  90 For an explanation of the terms used in this section, see
  91 .BR attributes (7).
  92 .ad l
  93 .nh
  94 .TS
  95 allbox;
  96 lbx lb lb
  97 l l l.
  98 Interface       Attribute       Value
  99 T{
 100 .BR fgetpwent ()
 101 T}      Thread safety   MT-Unsafe race:fgetpwent
 102 .TE
 103 .hy
 104 .ad
 105 .sp 1
 106 .\" FIXME: The marking is different from that in the glibc manual,
 107 .\" which has:
 108 .\"
 109 .\"    fgetpwent: MT-Unsafe race:fpwent
 110 .\"
 111 .\" We think race:fpwent in glibc maybe hard for users to understand,
 112 .\" and have sent a patch to the GNU libc community for changing it to
 113 .\" race:fgetpwent, however, something about the copyright impeded the
 114 .\" progress.
 115 .SH STANDARDS
 116 SVr4.
 117 .SH SEE ALSO
 118 .BR endpwent (3),
 119 .BR fgetpwent_r (3),
 120 .BR fopen (3),
 121 .BR getpw (3),
 122 .BR getpwent (3),
 123 .BR getpwnam (3),
 124 .BR getpwuid (3),
 125 .BR putpwent (3),
 126 .BR setpwent (3),
 127 .BR passwd (5)