GNU Info

(libc.info)Lookup Netgroup

---

Next: Netgroup Membership Prev: Netgroup Data Up: Netgroup Database

---

Enter node , (file) or (file)node

Looking up one Netgroup
-----------------------

   The lookup functions for netgroups are a bit different to all other
system database handling functions.  Since a single netgroup can contain
many entries a two-step process is needed.  First a single netgroup is
selected and then one can iterate over all entries in this netgroup.
These functions are declared in `netdb.h'.

 - Function: int setnetgrent (const char *NETGROUP)
     A call to this function initializes the internal state of the
     library to allow following calls of the `getnetgrent' to iterate
     over all entries in the netgroup with name NETGROUP.

     When the call is successful (i.e., when a netgroup with this name
     exists) the return value is `1'.  When the return value is `0' no
     netgroup of this name is known or some other error occurred.

   It is important to remember that there is only one single state for
iterating the netgroups.  Even if the programmer uses the
`getnetgrent_r' function the result is not really reentrant since
always only one single netgroup at a time can be processed.  If the
program needs to process more than one netgroup simultaneously she must
protect this by using external locking.  This problem was introduced in
the original netgroups implementation in SunOS and since we must stay
compatible it is not possible to change this.

   Some other functions also use the netgroups state.  Currently these
are the `innetgr' function and parts of the implementation of the
`compat' service part of the NSS implementation.

 - Function: int getnetgrent (char **HOSTP, char **USERP, char
          **DOMAINP)
     This function returns the next unprocessed entry of the currently
     selected netgroup.  The string pointers, in which addresses are
     passed in the arguments HOSTP, USERP, and DOMAINP, will contain
     after a successful call pointers to appropriate strings.  If the
     string in the next entry is empty the pointer has the value `NULL'.
     The returned string pointers are only valid if none of the netgroup
     related functions are called.

     The return value is `1' if the next entry was successfully read.  A
     value of `0' means no further entries exist or internal errors
     occurred.

 - Function: int getnetgrent_r (char **HOSTP, char **USERP, char
          **DOMAINP, char *BUFFER, int BUFLEN)
     This function is similar to `getnetgrent' with only one exception:
     the strings the three string pointers HOSTP, USERP, and DOMAINP
     point to, are placed in the buffer of BUFLEN bytes starting at
     BUFFER.  This means the returned values are valid even after other
     netgroup related functions are called.

     The return value is `1' if the next entry was successfully read and
     the buffer contains enough room to place the strings in it.  `0' is
     returned in case no more entries are found, the buffer is too
     small, or internal errors occurred.

     This function is a GNU extension.  The original implementation in
     the SunOS libc does not provide this function.

 - Function: void endnetgrent (void)
     This function frees all buffers which were allocated to process
     the last selected netgroup.  As a result all string pointers
     returned by calls to `getnetgrent' are invalid afterwards.