GNU Info

(libc.info)Scanning All Groups

---

Prev: Lookup Group Up: Group Database

---

Enter node , (file) or (file)node

Scanning the List of All Groups
-------------------------------

   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 `grp.h'.

   You can use the `fgetgrent' function to read group entries from a
particular file.

 - Function: struct group * fgetgrent (FILE *STREAM)
     The `fgetgrent' function reads the next entry from STREAM.  It
     returns a pointer to the entry.  The structure is statically
     allocated and is overwritten on subsequent calls to `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.

 - Function: int fgetgrent_r (FILE *STREAM, struct group *RESULT_BUF,
          char *BUFFER, size_t BUFLEN, struct group **RESULT)
     This function is similar to `fgetgrent' in that it reads the next
     user entry from STREAM.  But the result is returned in the
     structure pointed to by RESULT_BUF.  The first BUFLEN bytes of the
     additional buffer pointed to by BUFFER are used to contain
     additional information, normally strings which are pointed to by
     the elements of the result structure.

     This stream must correspond to a file in the same format as the
     standard group database file.

     If the function returns zero RESULT points to the structure with
     the wanted data (normally this is in RESULT_BUF).  If errors
     occurred the return value is non-zero and RESULT contains a null
     pointer.

   The way to scan all the entries in the group database is with
`setgrent', `getgrent', and `endgrent'.

 - Function: void setgrent (void)
     This function initializes a stream for reading from the group data
     base.  You use this stream by calling `getgrent' or `getgrent_r'.

 - Function: struct group * getgrent (void)
     The `getgrent' function reads the next entry from the stream
     initialized by `setgrent'.  It returns a pointer to the entry.  The
     structure is statically allocated and is overwritten on subsequent
     calls to `getgrent'.  You must copy the contents of the structure
     if you wish to save the information.

 - Function: int getgrent_r (struct group *RESULT_BUF, char *BUFFER,
          size_t BUFLEN, struct group **RESULT)
     This function is similar to `getgrent' in that it returns the next
     entry from the stream initialized by `setgrent'.  Like
     `fgetgrent_r', it places the result in user-supplied buffers
     pointed to RESULT_BUF and BUFFER.

     If the function returns zero RESULT contains a pointer to the data
     (normally equal to RESULT_BUF).  If errors occurred the return
     value is non-zero and RESULT contains a null pointer.

 - Function: void endgrent (void)
     This function closes the internal stream used by `getgrent' or
     `getgrent_r'.