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