man3/fgetgrent.3

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