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