Return to if_util.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / net

libpdel

    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.1.1.1 2012/02/21 23:25:53 misho 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.