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