Annotation of embedaddon/libpdel/net/if_util.3, revision 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