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