lib/libc/rpc/getnetconfig.3

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