lib/libc/rpc/getnetpath.3

   1 .\"     @(#)getnetpath.3n 1.26 93/05/07 SMI; from SVr4
   2 .\"     $NetBSD: getnetpath.3,v 1.6 2003/04/16 13:34:43 wiz Exp $
   3 .\" Copyright 1989 AT&T
   4 .Dd April 22, 2000
   5 .Dt GETNETPATH 3
   6 .Os
   7 .Sh NAME
   8 .Nm getnetpath ,
   9 .Nm setnetpath ,
  10 .Nm endnetpath
  11 .Nd get /etc/netconfig entry corresponding to NETPATH component
  12 .Sh LIBRARY
  13 .Lb libc
  14 .Sh SYNOPSIS
  15 .In netconfig.h
  16 .Ft struct netconfig *
  17 .Fn getnetpath "void *handlep"
  18 .Ft void *
  19 .Fn setnetpath "void"
  20 .Ft int
  21 .Fn endnetpath "void *handlep"
  22 .Sh DESCRIPTION
  23 The routines described in this page provide the application access to the system
  24 network configuration database,
  25 .Pa /etc/netconfig ,
  26 as it is
  27 .Dq filtered
  28 by the NETPATH
  29 environment variable (see
  30 .Xr environ 7 ) .
  31 See
  32 .Xr getnetconfig 3
  33 for other routines that also access the
  34 network configuration database directly.
  35 The NETPATH variable is a list of colon-separated network identifiers.
  36 .Pp
  37 .Fn getnetpath
  38 returns a pointer to the
  39 netconfig database entry corresponding to the first valid
  40 NETPATH component.
  41 The netconfig entry is formatted as a struct netconfig.
  42 On each subsequent call,
  43 .Fn getnetpath
  44 returns a pointer to the netconfig entry that corresponds to the next
  45 valid NETPATH component.
  46 .Fn getnetpath
  47 can thus be used to search the netconfig database for all networks
  48 included in the NETPATH variable.
  49 When NETPATH has been exhausted,
  50 .Fn getnetpath
  51 returns NULL.
  52 .Pp
  53 A call to
  54 .Fn setnetpath
  55 .Dq binds
  56 to or
  57 .Dq rewinds
  58 NETPATH.
  59 .Fn setnetpath
  60 must be called before the first call to
  61 .Fn getnetpath
  62 and may be called at any other time.
  63 It returns a handle that is used by
  64 .Fn getnetpath .
  65 .Pp
  66 .Fn getnetpath
  67 silently ignores invalid NETPATH
  68 components.
  69 A NETPATH component is invalid if there is no corresponding
  70 entry in the netconfig database.
  71 .Pp
  72 If the NETPATH variable is unset,
  73 .Fn getnetpath
  74 behaves as if NETPATH
  75 were set to the sequence of
  76 .Dq default
  77 or
  78 .Dq visible
  79 networks in the netconfig database, in the
  80 order in which they are listed.
  81 .\"This proviso holds also for this
  82 .\"whole manpage.
  83 .Pp
  84 .Fn endnetpath
  85 may be called to
  86 .Dq unbind
  87 from NETPATH
  88 when processing is complete, releasing resources for reuse.
  89 Programmers should be aware, however, that
  90 .Fn endnetpath
  91 frees all memory allocated by
  92 .Fn getnetpath
  93 for the struct netconfig data structure.
  94 .Sh RETURN VALUES
  95 .Fn setnetpath
  96 returns a handle that is used by
  97 .Fn getnetpath .
  98 In case of an error,
  99 .Fn setnetpath
 100 returns NULL.
 101 .Pp
 102 .Fn endnetpath
 103 returns 0 on success and -1 on failure
 104 (for example, if
 105 .Fn setnetpath
 106 was not called previously).
 107 .Fn nc_perror
 108 or
 109 .Fn nc_sperror
 110 can be used to print out the reason for failure.
 111 See
 112 .Xr getnetconfig 3 .
 113 .Pp
 114 When first called,
 115 .Fn getnetpath
 116 returns a pointer to the netconfig database entry corresponding to the first
 117 valid NETPATH component.
 118 When NETPATH has been exhausted,
 119 .Fn getnetpath
 120 returns NULL.
 121 .Sh SEE ALSO
 122 .Xr getnetconfig 3 ,
 123 .Xr netconfig 5 ,
 124 .Xr environ 7