man/getnetpath.3t

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