reactos/dll/win32/libtirpc/man/getnetconfig.3t

   1 .\" @(#)getnetconfig.3n 1.28 93/06/02 SMI; from SVr4
   2 .\" Copyright 1989 AT&T
   3 .Dd April 22, 2000
   4 .Dt GETNETCONFIG 3
   5 .Os
   6 .Sh NAME
   7 .Nm getnetconfig ,
   8 .Nm setnetconfig ,
   9 .Nm endnetconfig ,
  10 .Nm getnetconfigent ,
  11 .Nm freenetconfigent ,
  12 .Nm nc_perror ,
  13 .Nm nc_sperror
  14 .Nd get network configuration database entry
  15 .Sh LIBRARY
  16 .Lb libc
  17 .Sh SYNOPSIS
  18 .In netconfig.h
  19 .Ft "struct netconfig *"
  20 .Fn getnetconfig "void *handlep"
  21 .Ft "void *"
  22 .Fn setnetconfig "void"
  23 .Ft int
  24 .Fn endnetconfig "void *handlep"
  25 .Ft "struct netconfig *"
  26 .Fn getnetconfigent "const char *netid"
  27 .Ft void
  28 .Fn freenetconfigent "struct netconfig *netconfigp"
  29 .Ft void
  30 .Fn nc_perror "const char *msg"
  31 .Ft "char *"
  32 .Fn nc_sperror "void"
  33 .Sh DESCRIPTION
  34 The library routines described on this page
  35 provide the application access to
  36 the system network configuration database,
  37 .Pa /etc/netconfig .
  38 The
  39 .Fn getnetconfig
  40 function
  41 returns a pointer to the
  42 current entry in the
  43 netconfig
  44 database, formatted as a
  45 .Ft "struct netconfig" .
  46 Successive calls will return successive netconfig
  47 entries in the netconfig database.
  48 The
  49 .Fn getnetconfig
  50 function
  51 can be used to search the entire netconfig
  52 file.
  53 The
  54 .Fn getnetconfig
  55 function
  56 returns
  57 .Dv NULL
  58 at the end of the file.
  59 The
  60 .Fa handlep
  61 argument
  62 is the handle obtained through
  63 .Fn setnetconfig .
  64 .Pp
  65 A call to
  66 .Fn setnetconfig
  67 has the effect of
  68 .Dq binding
  69 to or
  70 .Dq rewinding
  71 the netconfig database.
  72 The
  73 .Fn setnetconfig
  74 function
  75 must be called before the first call to
  76 .Fn getnetconfig
  77 and may be called at any other time.
  78 The
  79 .Fn setnetconfig
  80 function
  81 need not be called before a call to
  82 .Fn getnetconfigent .
  83 The
  84 .Fn setnetconfig
  85 function
  86 returns a unique handle to be used by
  87 .Fn getnetconfig .
  88 .Pp
  89 The
  90 .Fn endnetconfig
  91 function
  92 should be called when processing is complete to release resources for reuse.
  93 The
  94 .Fa handlep
  95 argument
  96 is the handle obtained through
  97 .Fn setnetconfig .
  98 Programmers should be aware, however, that the last call to
  99 .Fn endnetconfig
 100 frees all memory allocated by
 101 .Fn getnetconfig
 102 for the
 103 .Ft "struct netconfig"
 104 data structure.
 105 The
 106 .Fn endnetconfig
 107 function
 108 may not be called before
 109 .Fn setnetconfig .
 110 .Pp
 111 The
 112 .Fn getnetconfigent
 113 function
 114 returns a pointer
 115 to the netconfig structure corresponding
 116 to
 117 .Fa netid .
 118 It returns
 119 .Dv NULL
 120 if
 121 .Fa netid
 122 is invalid
 123 (that is, does not name an entry in the netconfig database).
 124 .Pp
 125 The
 126 .Fn freenetconfigent
 127 function
 128 frees the netconfig structure pointed to by
 129 .Fa netconfigp
 130 (previously returned by
 131 .Fn getnetconfigent ) .
 132 .Pp
 133 The
 134 .Fn nc_perror
 135 function
 136 prints a message to the standard error indicating why any of the
 137 above routines failed.
 138 The message is prepended with the string
 139 .Fa msg
 140 and a colon.
 141 A newline character is appended at the end of the message.
 142 .Pp
 143 The
 144 .Fn nc_sperror
 145 function
 146 is similar to
 147 .Fn nc_perror
 148 but instead of sending the message
 149 to the standard error, will return a pointer to a string that
 150 contains the error message.
 151 .Pp
 152 The
 153 .Fn nc_perror
 154 and
 155 .Fn nc_sperror
 156 functions
 157 can also be used with the
 158 .Ev NETPATH
 159 access routines defined in
 160 .Xr getnetpath 3 .
 161 .Sh RETURN VALUES
 162 The
 163 .Fn setnetconfig
 164 function
 165 returns a unique handle to be used by
 166 .Fn getnetconfig .
 167 In the case of an error,
 168 .Fn setnetconfig
 169 returns
 170 .Dv NULL
 171 and
 172 .Fn nc_perror
 173 or
 174 .Fn nc_sperror
 175 can be used to print the reason for failure.
 176 .Pp
 177 The
 178 .Fn getnetconfig
 179 function
 180 returns a pointer to the current entry in the netconfig
 181 database, formatted as a
 182 .Ft "struct netconfig" .
 183 The
 184 .Fn getnetconfig
 185 function
 186 returns
 187 .Dv NULL
 188 at the end of the file, or upon failure.
 189 .Pp
 190 The
 191 .Fn endnetconfig
 192 function
 193 returns 0 on success and \-1 on failure
 194 (for example, if
 195 .Fn setnetconfig
 196 was not called previously).
 197 .Pp
 198 On success,
 199 .Fn getnetconfigent
 200 returns a pointer to the
 201 .Ft "struct netconfig"
 202 structure corresponding to
 203 .Fa netid ;
 204 otherwise it returns
 205 .Dv NULL .
 206 .Pp
 207 The
 208 .Fn nc_sperror
 209 function
 210 returns a pointer to a buffer which contains the error message string.
 211 This buffer is overwritten on each call.
 212 In multithreaded applications, this buffer is
 213 implemented as thread-specific data.
 214 .Sh FILES
 215 .Bl -tag -width /etc/netconfig -compact
 216 .It Pa /etc/netconfig
 217 .El
 218 .Sh SEE ALSO
 219 .Xr getnetpath 3 ,
 220 .Xr netconfig 5