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