Return to route_msg.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: route_msg.3,v 1.1.1.1 2012/02/21 23:25:53 misho Exp $
   39: .\"
   40: .Dd April 22, 2002
   41: .Dt ROUTE_MSG 3
   42: .Os
   43: .Sh NAME
   44: .Nm route_msg
   45: .Nd routing socket message objects
   46: .Sh LIBRARY
   47: PDEL Library (libpdel, \-lpdel)
   48: .Sh SYNOPSIS
   49: .In sys/types.h
   50: .In stdio.h
   51: .In pdel/net/route_msg.h
   52: .Ft "struct route_msg *"
   53: .Fn route_msg_create "void"
   54: .Ft "void"
   55: .Fn route_msg_destroy "struct route_msg **msgp"
   56: .Ft "int"
   57: .Fn route_msg_get_type "struct route_msg *msg"
   58: .Ft "void"
   59: .Fn route_msg_set_type "struct route_msg *msg" "int type"
   60: .Ft "int"
   61: .Fn route_msg_get_index "struct route_msg *msg"
   62: .Ft "void"
   63: .Fn route_msg_set_index "struct route_msg *msg" "int index"
   64: .Ft "int"
   65: .Fn route_msg_get_flags "struct route_msg *msg"
   66: .Ft "void"
   67: .Fn route_msg_set_flags "struct route_msg *msg" "int flags"
   68: .Ft "int"
   69: .Fn route_msg_get_error "struct route_msg *msg"
   70: .Ft "pid_t"
   71: .Fn route_msg_get_pid "struct route_msg *msg"
   72: .Ft "int"
   73: .Fn route_msg_get_seq "struct route_msg *msg"
   74: .Ft "const struct sockaddr *"
   75: .Fn route_msg_get_dest "struct route_msg *msg"
   76: .Ft "int"
   77: .Fn route_msg_set_dest "struct route_msg *msg" "const struct sockaddr *dest"
   78: .Ft "const struct sockaddr *"
   79: .Fn route_msg_get_gateway "struct route_msg *msg"
   80: .Ft "int"
   81: .Fn route_msg_set_gateway "struct route_msg *msg" "const struct sockaddr *gateway"
   82: .Ft "const struct sockaddr *"
   83: .Fn route_msg_get_netmask "struct route_msg *msg"
   84: .Ft "int"
   85: .Fn route_msg_set_netmask "struct route_msg *msg" "const struct sockaddr *netmask"
   86: .Ft "const struct sockaddr *"
   87: .Fn route_msg_get_genmask "struct route_msg *msg"
   88: .Ft "int"
   89: .Fn route_msg_set_genmask "struct route_msg *msg" "const struct sockaddr *genmask"
   90: .Ft "const struct sockaddr *"
   91: .Fn route_msg_get_ifp "struct route_msg *msg"
   92: .Ft "int"
   93: .Fn route_msg_set_ifp "struct route_msg *msg" "const struct sockaddr *ifp"
   94: .Ft "const struct sockaddr *"
   95: .Fn route_msg_get_ifa "struct route_msg *msg"
   96: .Ft "int"
   97: .Fn route_msg_set_ifa "struct route_msg *msg" "const struct sockaddr *ifa"
   98: .Ft "const struct sockaddr *"
   99: .Fn route_msg_get_author "struct route_msg *msg"
  100: .Ft "int"
  101: .Fn route_msg_set_author "struct route_msg *msg" "const struct sockaddr *author"
  102: .Ft "const struct sockaddr *"
  103: .Fn route_msg_get_brd "struct route_msg *msg"
  104: .Ft "int"
  105: .Fn route_msg_set_brd "struct route_msg *msg" "const struct sockaddr *brd"
  106: .Ft "int"
  107: .Fn route_msg_decode "const u_char *data" "size_t dlen" "struct route_msg ***listp" "const char *mtype"
  108: .Ft "int"
  109: .Fn route_msg_encode "const struct route_msg *msg" "u_char *data" "size_t dlen"
  110: .Ft "void"
  111: .Fn route_msg_print "struct route_msg *msg" "FILE *fp"
  112: .Ft "int"
  113: .Fn route_msg_send "struct route_msg *msg" "int sock"
  114: .Ft "int"
  115: .Fn route_msg_recv "struct route_msg ***listp" "int sock" "const char *mtype"
  116: .Sh DESCRIPTION
  117: These functions support
  118: .Nm "route_msg"
  119: objects, used for communication over kernel routing sockets.
  120: The routing socket messages are defined in the header file
  121: .Li "<net/route.h>" .
  122: Each
  123: .Nm route_msg
  124: instance is represented by a
  125: .Li "struct route_msg" .
  126: .Pp
  127: .Fn route_msg_create
  128: creates a new, empty
  129: .Nm route_msg
  130: object.
  131: .Pp
  132: .Fn route_msg_destroy
  133: destroys the object pointed to by
  134: .Fa "*msgp" .
  135: Upon return,
  136: .Fa "*msgp"
  137: will be set to
  138: .Dv NULL .
  139: If
  140: .Fa "*msgp"
  141: is already
  142: .Dv NULL
  143: when
  144: .Fn route_msg_destroy
  145: is invoked, nothing happens.
  146: .Pp
  147: The
  148: .Fn route_msg_get_XXX
  149: and
  150: .Fn route_msg_set_XXX
  151: routines allow reading and changing the attributes associated with a
  152: .Nm route_msg
  153: object.
  154: .Pp
  155: .Fn route_msg_decode
  156: decodes routing messages from data encoded in the format used when
  157: communicating over kernel routing sockets.
  158: The encoded data is pointed to by
  159: .Fa data
  160: and has length
  161: .Fa dlen .
  162: Zero or more
  163: .Nm route_msg
  164: objects are constructed and pointed to by the elements of a newly
  165: allocated array of pointers.
  166: The length of the array is returned by
  167: .Fn route_msg_decode
  168: and a pointer to the array is stored in
  169: .Fa "*listp" .
  170: The array itself is allocated with
  171: .Xr typed_mem 3
  172: type
  173: .Fa mtype ,
  174: and the caller is responsible for eventually freeing it (as well as
  175: destroying the individudal
  176: .Nm route_msg
  177: objects).
  178: If the encoded data is invalid, -1 is returned with
  179: .Va errno
  180: set to
  181: .Er EINVAL .
  182: .Pp
  183: .Fn route_msg_encode
  184: encodes a
  185: .Nm route_msg
  186: object into the format used when communicating over kernel routing sockets.
  187: The resulting data is stored in the buffer pointed to by
  188: .Fa data ,
  189: which must have length at least
  190: .Fa dlen .
  191: If the encoding does not fit in
  192: .Fa dlen
  193: bytes, -1 is returned with
  194: .Va errno
  195: set to
  196: .Er EMSGSIZE .
  197: Otherwise, the number of bytes actually written into
  198: .Fa data
  199: is returned.
  200: .Pp
  201: .Fn route_msg_print
  202: prints out a
  203: .Nm route_msg
  204: object to the stream
  205: .Fa fp
  206: for debugging purposes.
  207: .Pp
  208: .Fn route_msg_send
  209: encodes and writes the
  210: .Nm route_msg
  211: object to the routing socket descriptor
  212: .Fa sock .
  213: .Pp
  214: .Nm route_msg_recv
  215: reads the next packet from the routing socket descriptor
  216: .Fa sock
  217: and decodes
  218: .Nm route_msg
  219: objects from the data read.
  220: The
  221: .Fa listp
  222: and
  223: .Fa mtype
  224: parameters are the same as with
  225: .Fn route_msg_decode .
  226: .Sh RETURN VALUES
  227: Except for functions returning
  228: .Li "void" ,
  229: all of the above functions return -1 or
  230: .Dv NULL
  231: to indicate an error, with
  232: .Va errno
  233: set appropriately.
  234: .Sh SEE ALSO
  235: .Xr if_util 3 ,
  236: .Xr libpdel 3 ,
  237: .Xr typed_mem 3 ,
  238: .Xr uroute 3 ,
  239: .Xr route 4
  240: .Sh HISTORY
  241: The PDEL library was developed at Packet Design, LLC.
  242: .Dv "http://www.packetdesign.com/"
  243: .Sh AUTHORS
  244: .An Archie Cobbs Aq archie@freebsd.org