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 .\" 4. 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: src/lib/libc/gen/getnetgrent.3,v 1.6.2.5 2003/03/13 18:05:37 trhodes Exp $
  30 .\" $DragonFly: src/lib/libc/gen/getnetgrent.3,v 1.3 2006/02/17 19:35:06 swildner Exp $
  31 .\"
  32 .Dd June 4, 1993
  33 .Dt GETNETGRENT 3
  34 .Os
  35 .Sh NAME
  36 .Nm getnetgrent ,
  37 .Nm innetgr ,
  38 .Nm setnetgrent ,
  39 .Nm endnetgrent
  40 .Nd netgroup database operations
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In netdb.h
  45 .Ft int
  46 .Fn getnetgrent "char **host" "char **user" "char **domain"
  47 .Ft int
  48 .Fn innetgr "const char *netgroup" "const char *host" "const char *user" "const char *domain"
  49 .Ft void
  50 .Fn setnetgrent "const char *netgroup"
  51 .Ft void
  52 .Fn endnetgrent void
  53 .Sh DESCRIPTION
  54 These functions operate on the netgroup database file
  55 .Pa /etc/netgroup
  56 which is described
  57 in
  58 .Xr netgroup 5 .
  59 The database defines a set of netgroups, each made up of one or more triples:
  60 .Bd -literal -offset indent
  61 (host, user, domain)
  62 .Ed
  63 that defines a combination of host, user and domain.
  64 Any of the three fields may be specified as ``wildcards'' that match any
  65 string.
  66 .Pp
  67 The function
  68 .Fn getnetgrent
  69 sets the three pointer arguments to the strings of the next member of the
  70 current netgroup.
  71 If any of the string pointers are
  72 .Dv NULL
  73 that field is considered a wildcard.
  74 .Pp
  75 The functions
  76 .Fn setnetgrent
  77 and
  78 .Fn endnetgrent
  79 set the current netgroup and terminate the current netgroup respectively.
  80 If
  81 .Fn setnetgrent
  82 is called with a different netgroup than the previous call, an implicit
  83 .Fn endnetgrent
  84 is implied.
  85 The
  86 .Fn setnetgrent
  87 function
  88 also sets the offset to the first member of the netgroup.
  89 .Pp
  90 The function
  91 .Fn innetgr
  92 searches for a match of all fields within the specified group.
  93 If any of the
  94 .Fa host ,
  95 .Fa user ,
  96 or
  97 .Fa domain
  98 arguments are
  99 .Dv NULL
 100 those fields will match any string value in the netgroup member.
 101 .Sh RETURN VALUES
 102 The function
 103 .Fn getnetgrent
 104 returns 0 for ``no more netgroup members'' and 1 otherwise.
 105 The function
 106 .Fn innetgr
 107 returns 1 for a successful match and 0 otherwise.
 108 The functions
 109 .Fn setnetgrent
 110 and
 111 .Fn endnetgrent
 112 have no return value.
 113 .Sh FILES
 114 .Bl -tag -width /etc/netgroup -compact
 115 .It Pa /etc/netgroup
 116 netgroup database file
 117 .El
 118 .Sh COMPATIBILITY
 119 The netgroup members have three string fields to maintain compatibility
 120 with other vendor implementations, however it is not obvious what use the
 121 .Fa domain
 122 string has within
 123 .Bx .
 124 .Sh SEE ALSO
 125 .Xr netgroup 5
 126 .Sh BUGS
 127 The function
 128 .Fn getnetgrent
 129 returns pointers to dynamically allocated data areas that are freed when
 130 the function
 131 .Fn endnetgrent
 132 is called.