lib/libc/rpc/getnetpath.3

   1 .\" @(#)getnetpath.3n 1.26 93/05/07 SMI; from SVr4
   2 .\" $NetBSD: getnetpath.3,v 1.1 2000/06/02 23:11:11 fvdl Exp $
   3 .\" $FreeBSD: src/lib/libc/rpc/getnetpath.3,v 1.5 2002/12/18 12:45:10 ru Exp $
   4 .\" $DragonFly$
   5 .\" Copyright 1989 AT&T
   6 .Dd November 15, 2008
   7 .Dt GETNETPATH 3
   8 .Os
   9 .Sh NAME
  10 .Nm getnetpath ,
  11 .Nm setnetpath ,
  12 .Nm endnetpath
  13 .Nd get
  14 .Pa /etc/netconfig
  15 entry corresponding to
  16 .Ev NETPATH
  17 component
  18 .Sh LIBRARY
  19 .Lb libc
  20 .Sh SYNOPSIS
  21 .In netconfig.h
  22 .Ft "struct netconfig *"
  23 .Fn getnetpath "void *handlep"
  24 .Ft "void *"
  25 .Fn setnetpath "void"
  26 .Ft int
  27 .Fn endnetpath "void *handlep"
  28 .Sh DESCRIPTION
  29 The routines described in this page provide the application access to the system
  30 network configuration database,
  31 .Pa /etc/netconfig ,
  32 as it is
  33 .Dq filtered
  34 by the
  35 .Ev NETPATH
  36 environment variable (see
  37 .Xr environ 7 ) .
  38 See
  39 .Xr getnetconfig 3
  40 for other routines that also access the
  41 network configuration database directly.
  42 The
  43 .Ev NETPATH
  44 variable is a list of colon-separated network identifiers.
  45 .Pp
  46 The
  47 .Fn getnetpath
  48 function
  49 returns a pointer to the
  50 netconfig database entry corresponding to the first valid
  51 .Ev NETPATH
  52 component.
  53 The netconfig entry is formatted as a
  54 .Ft "struct netconfig" .
  55 On each subsequent call,
  56 .Fn getnetpath
  57 returns a pointer to the netconfig entry that corresponds to the next
  58 valid
  59 .Ev NETPATH
  60 component.
  61 The
  62 .Fn getnetpath
  63 function
  64 can thus be used to search the netconfig database for all networks
  65 included in the
  66 .Ev NETPATH
  67 variable.
  68 When
  69 .Ev NETPATH
  70 has been exhausted,
  71 .Fn getnetpath
  72 returns
  73 .Dv NULL .
  74 .Pp
  75 A call to
  76 .Fn setnetpath
  77 .Dq binds
  78 to or
  79 .Dq rewinds
  80 .Ev NETPATH .
  81 The
  82 .Fn setnetpath
  83 function
  84 must be called before the first call to
  85 .Fn getnetpath
  86 and may be called at any other time.
  87 It returns a handle that is used by
  88 .Fn getnetpath .
  89 .Pp
  90 The
  91 .Fn getnetpath
  92 function
  93 silently ignores invalid
  94 .Ev NETPATH
  95 components.
  96 A
  97 .Ev NETPATH
  98 component is invalid if there is no corresponding
  99 entry in the netconfig database.
 100 .Pp
 101 If the
 102 .Ev NETPATH
 103 variable is unset,
 104 .Fn getnetpath
 105 behaves as if
 106 .Ev NETPATH
 107 were set to the sequence of
 108 .Dq default
 109 or
 110 .Dq visible
 111 networks in the netconfig database, in the
 112 order in which they are listed.
 113 .\"This proviso holds also for this
 114 .\"whole manpage.
 115 .Pp
 116 The
 117 .Fn endnetpath
 118 function
 119 may be called to
 120 .Dq unbind
 121 from
 122 .Ev NETPATH
 123 when processing is complete, releasing resources for reuse.
 124 Programmers should be aware, however, that
 125 .Fn endnetpath
 126 frees all memory allocated by
 127 .Fn getnetpath
 128 for the struct netconfig data structure.
 129 .Sh RETURN VALUES
 130 The
 131 .Fn setnetpath
 132 function
 133 returns a handle that is used by
 134 .Fn getnetpath .
 135 In case of an error,
 136 .Fn setnetpath
 137 returns
 138 .Dv NULL .
 139 .Pp
 140 The
 141 .Fn endnetpath
 142 function
 143 returns 0 on success and \-1 on failure
 144 (for example, if
 145 .Fn setnetpath
 146 was not called previously).
 147 The
 148 .Fn nc_perror
 149 or
 150 .Fn nc_sperror
 151 function
 152 can be used to print out the reason for failure.
 153 See
 154 .Xr getnetconfig 3 .
 155 .Pp
 156 When first called,
 157 .Fn getnetpath
 158 returns a pointer to the netconfig database entry corresponding to the first
 159 valid
 160 .Ev NETPATH
 161 component.
 162 When
 163 .Ev NETPATH
 164 has been exhausted,
 165 .Fn getnetpath
 166 returns
 167 .Dv NULL .
 168 .Sh SEE ALSO
 169 .Xr getnetconfig 3 ,
 170 .Xr netconfig 5 ,
 171 .Xr environ 7