Annotation of embedaddon/libpdel/net/route_msg.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: route_msg.3,v 1.7 2004/06/02 17:24:37 archie 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
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to route_msg.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