lib/libc/gen/getnetgrent.3

   1 .\" Copyright (c) 1992, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)getnetgrent.3       8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd June 5, 2016
  32 .Dt GETNETGRENT 3
  33 .Os
  34 .Sh NAME
  35 .Nm getnetgrent ,
  36 .Nm innetgr ,
  37 .Nm setnetgrent ,
  38 .Nm endnetgrent
  39 .Nd netgroup database operations
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In netdb.h
  44 .Ft int
  45 .Fn getnetgrent "char **host" "char **user" "char **domain"
  46 .Ft int
  47 .Fn getnetgrent_r "char **host" "char **user" "char **domain" "char *buf" "size_t bufsize"
  48 .Ft int
  49 .Fn innetgr "const char *netgroup" "const char *host" "const char *user" "const char *domain"
  50 .Ft void
  51 .Fn setnetgrent "const char *netgroup"
  52 .Ft void
  53 .Fn endnetgrent void
  54 .Sh DESCRIPTION
  55 These functions operate on the netgroup database file
  56 .Pa /etc/netgroup
  57 which is described
  58 in
  59 .Xr netgroup 5 .
  60 The database defines a set of netgroups, each made up of one or more triples:
  61 .Bd -literal -offset indent
  62 (host, user, domain)
  63 .Ed
  64 that defines a combination of host, user and domain.
  65 Any of the three fields may be specified as ``wildcards'' that match any
  66 string.
  67 .Pp
  68 The function
  69 .Fn getnetgrent
  70 sets the three pointer arguments to the strings of the next member of the
  71 current netgroup.
  72 If any of the string pointers are
  73 .Dv NULL
  74 that field is considered a wildcard.
  75 .Pp
  76 The functions
  77 .Fn setnetgrent
  78 and
  79 .Fn endnetgrent
  80 set the current netgroup and terminate the current netgroup respectively.
  81 If
  82 .Fn setnetgrent
  83 is called with a different netgroup than the previous call, an implicit
  84 .Fn endnetgrent
  85 is implied.
  86 The
  87 .Fn setnetgrent
  88 function
  89 also sets the offset to the first member of the netgroup.
  90 .Pp
  91 The function
  92 .Fn innetgr
  93 searches for a match of all fields within the specified group.
  94 If any of the
  95 .Sy host ,
  96 .Sy user ,
  97 or
  98 .Sy domain
  99 arguments are
 100 .Dv NULL
 101 those fields will match any string value in the netgroup member.
 102 .Sh RETURN VALUES
 103 The function
 104 .Fn getnetgrent
 105 returns 0 for ``no more netgroup members'' and 1 otherwise.
 106 The function
 107 .Fn innetgr
 108 returns 1 for a successful match and 0 otherwise.
 109 The functions
 110 .Fn setnetgrent
 111 and
 112 .Fn endnetgrent
 113 have no return value.
 114 .Sh FILES
 115 .Bl -tag -width /etc/netgroup -compact
 116 .It Pa /etc/netgroup
 117 netgroup database file
 118 .El
 119 .Sh COMPATIBILITY
 120 The netgroup members have three string fields to maintain compatibility
 121 with other vendor implementations, however it is not obvious what use the
 122 .Sy domain
 123 string has within
 124 .Bx .
 125 .Sh SEE ALSO
 126 .Xr netgroup 5
 127 .Sh BUGS
 128 The function
 129 .Fn getnetgrent
 130 returns pointers to dynamically allocated data areas that are freed when
 131 the function
 132 .Fn endnetgrent
 133 is called.