lib/libc/rpc/getnetconfig.3

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