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