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