man3/setnetgrent.3

   1 '\" t
   2 .\"  Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de)
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-1.0-or-later
   5 .\"
   6 .\"  based on glibc infopages
   7 .\" polished - aeb
   8 .\"
   9 .TH setnetgrent 3 (date) "Linux man-pages (unreleased)"
  10 .SH NAME
  11 setnetgrent, endnetgrent, getnetgrent, getnetgrent_r, innetgr \-
  12 handle network group entries
  13 .SH LIBRARY
  14 Standard C library
  15 .RI ( libc ", " \-lc )
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <netdb.h>
  19 .PP
  20 .BI "int setnetgrent(const char *" netgroup );
  21 .B "void endnetgrent(void);"
  22 .PP
  23 .BI "int getnetgrent(char **restrict " host ,
  24 .BI "            char **restrict " user ", char **restrict " domain );
  25 .BI "int getnetgrent_r(char **restrict " host ,
  26 .BI "            char **restrict " user ", char **restrict " domain ,
  27 .BI "            char " buf "[restrict ." buflen "], size_t " buflen );
  28 .PP
  29 .BI "int innetgr(const char *" netgroup ", const char *" host ,
  30 .BI "            const char *" user ", const char *" domain );
  31 .fi
  32 .PP
  33 .RS -4
  34 Feature Test Macro Requirements for glibc (see
  35 .BR feature_test_macros (7)):
  36 .RE
  37 .ad l
  38 .PP
  39 .nh
  40 .BR setnetgrent (),
  41 .BR endnetgrent (),
  42 .BR getnetgrent (),
  43 .BR getnetgrent_r (),
  44 .BR innetgr ():
  45 .hy
  46 .nf
  47     Since glibc 2.19:
  48         _DEFAULT_SOURCE
  49     glibc 2.19 and earlier:
  50         _BSD_SOURCE || _SVID_SOURCE
  51 .fi
  52 .ad
  53 .SH DESCRIPTION
  54 The
  55 .I netgroup
  56 is a SunOS invention.
  57 A netgroup database is a list of string triples
  58 .RI ( hostname ", " username ", " domainname )
  59 or other netgroup names.
  60 Any of the elements in a triple can be empty,
  61 which means that anything matches.
  62 The functions described here allow access to the netgroup databases.
  63 The file
  64 .I /etc/nsswitch.conf
  65 defines what database is searched.
  66 .PP
  67 The
  68 .BR setnetgrent ()
  69 call defines the netgroup that will be searched by subsequent
  70 .BR getnetgrent ()
  71 calls.
  72 The
  73 .BR getnetgrent ()
  74 function retrieves the next netgroup entry, and returns pointers in
  75 .IR host ,
  76 .IR user ,
  77 .IR domain .
  78 A null pointer means that the corresponding entry matches any string.
  79 The pointers are valid only as long as there is no call to other
  80 netgroup-related functions.
  81 To avoid this problem you can use the GNU function
  82 .BR getnetgrent_r ()
  83 that stores the strings in the supplied buffer.
  84 To free all allocated buffers use
  85 .BR endnetgrent ().
  86 .PP
  87 In most cases you want to check only if the triplet
  88 .RI ( hostname ", " username ", " domainname )
  89 is a member of a netgroup.
  90 The function
  91 .BR innetgr ()
  92 can be used for this without calling the above three functions.
  93 Again, a null pointer is a wildcard and matches any string.
  94 The function is thread-safe.
  95 .SH RETURN VALUE
  96 These functions return 1 on success and 0 for failure.
  97 .SH FILES
  98 .I /etc/netgroup
  99 .br
 100 .I /etc/nsswitch.conf
 101 .SH ATTRIBUTES
 102 For an explanation of the terms used in this section, see
 103 .BR attributes (7).
 104 .ad l
 105 .nh
 106 .TS
 107 allbox;
 108 lb lb lbx
 109 l l l.
 110 Interface       Attribute       Value
 111 T{
 112 .BR setnetgrent (),
 113 .BR getnetgrent_r (),
 114 .BR innetgr ()
 115 T}      Thread safety   T{
 116 MT-Unsafe race:netgrent
 117 locale
 118 T}
 119 T{
 120 .BR endnetgrent ()
 121 T}      Thread safety   T{
 122 MT-Unsafe race:netgrent
 123 T}
 124 T{
 125 .BR getnetgrent ()
 126 T}      Thread safety   T{
 127 MT-Unsafe race:netgrent
 128 race:netgrentbuf locale
 129 T}
 130 .TE
 131 .hy
 132 .ad
 133 .sp 1
 134 In the above table,
 135 .I netgrent
 136 in
 137 .I race:netgrent
 138 signifies that if any of the functions
 139 .BR setnetgrent (),
 140 .BR getnetgrent_r (),
 141 .BR innetgr (),
 142 .BR getnetgrent (),
 143 or
 144 .BR endnetgrent ()
 145 are used in parallel in different threads of a program,
 146 then data races could occur.
 147 .SH STANDARDS
 148 These functions are not in POSIX.1, but
 149 .BR setnetgrent (),
 150 .BR endnetgrent (),
 151 .BR getnetgrent (),
 152 and
 153 .BR innetgr ()
 154 are available on most UNIX systems.
 155 .BR getnetgrent_r ()
 156 is not widely available on other systems.
 157 .\" getnetgrent_r() is on Solaris 8 and AIX 5.1, but not the BSDs.
 158 .SH NOTES
 159 In the BSD implementation,
 160 .BR setnetgrent ()
 161 returns void.
 162 .SH SEE ALSO
 163 .BR sethostent (3),
 164 .BR setprotoent (3),
 165 .BR setservent (3)