Annotation of embedaddon/libpdel/net/if_util.3, revision 1.1.1.1
1.1 misho 1: .\" Copyright (c) 2001-2002 Packet Design, LLC.
2: .\" All rights reserved.
3: .\"
4: .\" Subject to the following obligations and disclaimer of warranty,
5: .\" use and redistribution of this software, in source or object code
6: .\" forms, with or without modifications are expressly permitted by
7: .\" Packet Design; provided, however, that:
8: .\"
9: .\" (i) Any and all reproductions of the source or object code
10: .\" must include the copyright notice above and the following
11: .\" disclaimer of warranties; and
12: .\" (ii) No rights are granted, in any manner or form, to use
13: .\" Packet Design trademarks, including the mark "PACKET DESIGN"
14: .\" on advertising, endorsements, or otherwise except as such
15: .\" appears in the above copyright notice or in the software.
16: .\"
17: .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
18: .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
19: .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
20: .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
21: .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
22: .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
23: .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
24: .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
25: .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
26: .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
27: .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
28: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
29: .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
30: .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
31: .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
33: .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
34: .\" THE POSSIBILITY OF SUCH DAMAGE.
35: .\"
36: .\" Author: Archie Cobbs <archie@freebsd.org>
37: .\"
38: .\" $Id: if_util.3,v 1.6 2004/06/20 19:08:32 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt IF_UTIL 3
42: .Os
43: .Sh NAME
44: .Nm if_util
45: .Nd system networking interface utility routines
46: .Sh LIBRARY
47: PDEL Library (libpdel, \-lpdel)
48: .Sh SYNOPSIS
49: .In sys/types.h
50: .In netinet/in.h
51: .In pdel/net/if_util.h
52: .Ft int
53: .Fn if_get_list "char ***listp" "const char *mtype"
54: .Ft int
55: .Fn if_get_type "const char *ifname"
56: .Ft int
57: .Fn if_get_flags "const char *ifname"
58: .Ft int
59: .Fn if_set_flags "const char *ifname" "int flags"
60: .Ft int
61: .Fn if_get_mtu "const char *ifname"
62: .Ft int
63: .Fn if_set_mtu "const char *ifname" "u_int mtu"
64: .Ft int
65: .Fn if_get_link_addr "const char *ifname" "struct sockaddr_dl **sdlp" "const char *mtype"
66: .Ft int
67: .Fn if_get_ip_addrs "const char *ifname" "struct in_addr **iplistp" "struct in_addr **nmlistp" "const char *mtype"
68: .Ft int
69: .Fn if_get_ip_addr "const char *ifname" "struct in_addr *ipp" "struct in_addr *nmp"
70: .Ft int
71: .Fn if_add_ip_addr "const char *iface" "struct in_addr ip" "struct in_addr mask" "struct in_addr dest"
72: .Ft int
73: .Fn if_del_ip_addr "const char *iface" "struct in_addr ip" "struct in_addr mask" "struct in_addr dest"
74: .Ft int
75: .Fn if_get_arp "struct in_addr ip" "u_char *ether"
76: .Ft int
77: .Fn if_set_arp "struct in_addr ip" "const u_char *ether" "int temp" "int publish"
78: .Ft int
79: .Fn if_flush_arp "void"
80: .Sh DESCRIPTION
81: These functions are useful for accessing and configuring system networking
82: interfaces, especially for IP networking.
83: .Pp
84: .Fn if_get_list
85: constructs a list of the names of all interfaces present in the system.
86: Zero or more strings are allocated and pointed to by the elements of a newly
87: allocated array of pointers.
88: The length of the array is returned by
89: .Fn if_get_list
90: and a pointer to the array is stored in
91: .Fa "*listp" .
92: Each string, as well as the array itself, is allocated with
93: .Xr typed_mem 3
94: type
95: .Fa mtype .
96: The caller is responsible for eventually freeing the individual
97: strings as well as the array itself.
98: .Pp
99: .Fn if_get_type
100: returns the type of the interface named
101: .Fa ifname .
102: The interface types are defined in the include file
103: .Li "<net/if_types.h>" .
104: .Pp
105: .Fn if_get_flags
106: gets the flags associated with the interface named
107: .Fa ifname .
108: The interface flags are defined in the include file
109: .Li "<net/if.h>" .
110: .Pp
111: .Fn if_set_flags
112: attempts to set the flags associated with the interface named
113: .Fa ifname .
114: .Pp
115: .Fn if_get_mtu
116: returns the current MTU associated with the interface named
117: .Fa ifname .
118: .Pp
119: .Fn if_set_mtu
120: attempts to set the MTU associated with the interface named
121: .Fa ifname .
122: .Pp
123: .Fn if_get_link_addr
124: retrieves the link layer address associated with the interface named
125: .Fa ifname ,
126: allocates a buffer with
127: .Xr typed_mem 3
128: type
129: .Fa mtype
130: to hold it, and stores a pointer to the buffer in
131: .Fa "*sdlp" .
132: The caller is responsible for eventually freeing the buffer.
133: The
134: .Li "struct sockaddr_dl"
135: type is defined in the include file
136: .Li "<net/if_dl.h>" .
137: .Pp
138: .Fn if_get_ip_addrs
139: retrieves the list of all IP addresses (with netmasks) configured on
140: the interface named
141: .Fa ifname .
142: The IP addresses and netmasks are stored in two arrays allocated with
143: .Xr typed_mem 3
144: type
145: .Fa mtype ,
146: and pointers to these arrays are stored in
147: .Fa "*iplistp"
148: and
149: .Fa "*nmlistp" ,
150: respectively.
151: The caller is responsible for eventually freeing the arrays.
152: The length of the arrays is returned.
153: .Pp
154: .Fn if_get_ip_addr
155: retrieves the first IP address and netmask configured on
156: the interface named
157: .Fa ifname
158: and stores them in
159: .Fa "*ipp"
160: and
161: .Fa "*nmp" ,
162: respectively.
163: .Pp
164: .Fn if_add_ip_addr
165: configures a new IP address on the interface named
166: .Fa ifname ,
167: using the netmask
168: .Fa mask
169: and destination
170: .Fa dest .
171: Existing IP addresses configured on the interface are not removed.
172: .Fa dest
173: should be 0.0.0.0 for non-point-to-point interfaces.
174: .Pp
175: .Fn if_del_ip_addr
176: removes a configured IP address, netmask, and destination
177: from the interface named
178: .Fa ifname .
179: .Fa dest
180: should be 0.0.0.0 for non-point-to-point interfaces.
181: .Pp
182: .Fn if_get_arp
183: retrieves the ARP table entry associated with the IP address
184: .Fa ip
185: and stores it in the buffer pointed to by
186: .Fa ether ,
187: which must be at least six bytes long.
188: .Pp
189: .Fn if_set_arp
190: sets an ARP table entry for the IP address
191: .Fa ip
192: to resolve to the Ethernet address pointed to by
193: .Fa ether .
194: The
195: .Fa temp
196: flag indicates a temporary entry.
197: The
198: .Fa publish
199: flag indicates that the local machine should proxy-ARP for this IP address.
200: If
201: .Fa ether
202: is
203: .Dv NULL ,
204: any matching ARP table entry is cleared.
205: The
206: .Pp
207: .Fn if_flush_arp
208: clears the ARP table.
209: .Sh RETURN VALUES
210: All of the above functions return -1 to indicate an error, with
211: .Va errno
212: set appropriately.
213: .Sh SEE ALSO
214: .Xr libpdel 3 ,
215: .Xr typed_mem 3 ,
216: .Xr route_msg 3 ,
217: .Xr uroute 3 ,
218: .Xr route 4
219: .Sh HISTORY
220: The PDEL library was developed at Packet Design, LLC.
221: .Dv "http://www.packetdesign.com/"
222: .Sh AUTHORS
223: .An Archie Cobbs Aq archie@freebsd.org
224: .Sh BUGS
225: There is no way to retrieve destination addresses configured
226: on a point-to-point interface.
227: .Pp
228: These routines should be less IPv4-centric.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to if_util.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / net