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