getnetgrent(3C)

DESCRIPTION

These functions are used to test membership in and enumerate members of ``netgroup'' network groups defined in a system database. Netgroups are sets of (machine,user,domain) triples (see netgroup(4)).

These functions consult the source specified for netgroup in the /etc/nsswitch.conf file (see nsswitch.conf(4)).

The function innetgr() returns 1 if there is a netgroup netgroup that contains the specified machine, user, domain triple as a member; otherwise it returns 0. Any of the supplied pointers machine, user, and domain may be NULL, signifying a ``wild card'' that matches all values in that position of the triple.

The innetgr() function is safe for use in multithreaded applications.

The functions setnetgrent(), getnetgrent(), and endnetgrent() are used to enumerate the members of a given network group.

The function setnetgrent() establishes the network group specified in the parameter netgroup as the current group whose members are to be enumerated.

Successive calls to the function getnetgrent() will enumerate the members of the group established by calling setnetgrent(); each call returns 1 if it succeeds in obtaining another member of the network group, or 0 if there are no further members of the group.

When calling getnetgrent() addresses of the three character pointers are used as arguments; i.e.:

Upon successful return from getnetgrent(), the pointer mp points to a thread specific storage area containing the name of the machine part of the member triple, up points to a thread specific storage area containing the user name and dp points to a thread specific storage area containing the domain name. If the pointer returned for mp, up, or dp is NULL, it signifies that the element of the netgroup contains wild card specifier in that position of the triple.

The storage allocated by setnetgrent() is released when an endnetgrent() call is made, and should not be released by the caller.

The function endnetgrent() frees the space allocated by the previous setnetgrent() call. The equivalent of an endnetgrent() implicitly performed whenever a setnetgrent() call is made to a new network group.

Note that while setnetgrent() and endnetgrent() are safe for use in multi-threaded applications, the effect of each is process-wide. Calling setnetgrent() resets the enumeration position for all threads. If multiple threads interleave calls to getnetgrent_r() each will enumerate a disjoint subset of the netgroup. Thus the effective use of these functions in multi-threaded applications may require coordination by the caller.

MULTITHREAD USAGE

These functions can be called safely in a multithreaded environment. They may be cancellation points in that they call functions that are cancel points.

In a multithreaded environment, these functions are not safe to be called by a child process after fork() and before exec(). These functions should not be called by a multithreaded application that support asynchronous cancellation or asynchronous signals.

WARNINGS

Programs that use the interfaces described in this manual page cannot be linked statically since the implementations of these functions employ dynamic loading and linking of shared objects at run time.

FILES

SEE ALSO

netgroup(4), nsswitch.conf(4).