Markup fixes.
This commit is contained in:
ru
parent
25cdbb430a
commit
408d450c6b
@ -1,5 +1,3 @@
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.\" Copyright (c) 2003 Bruce M. Simpson. All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
@ -19,7 +17,10 @@
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.Dd October 12, 1995
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd November 14, 2003
|
||||
.Dt GETIFMADDRS 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
@ -40,11 +41,11 @@ function stores a reference to a linked list of the multicast memberships
|
||||
on the local machine in the memory referenced by
|
||||
.Fa ifmap .
|
||||
The list consists of
|
||||
.Nm ifmaddrs
|
||||
.Vt ifmaddrs
|
||||
structures, as defined in the include file
|
||||
.Aq Pa ifaddrs.h .
|
||||
.In ifaddrs.h .
|
||||
The
|
||||
.Nm ifmaddrs
|
||||
.Vt ifmaddrs
|
||||
structure contains at least the following entries:
|
||||
.Bd -literal
|
||||
struct ifmaddrs *ifma_next; /* Pointer to next struct */
|
||||
@ -54,26 +55,29 @@ structure contains at least the following entries:
|
||||
.Ed
|
||||
.Pp
|
||||
The
|
||||
.Li ifma_next
|
||||
.Va ifma_next
|
||||
field contains a pointer to the next structure on the list.
|
||||
This field is
|
||||
.Dv NULL
|
||||
in last structure on the list.
|
||||
.Pp
|
||||
The
|
||||
.Li ifma_name
|
||||
field references an AF_LINK address structure, containing the name of the
|
||||
.Va ifma_name
|
||||
field references an
|
||||
.Dv AF_LINK
|
||||
address structure, containing the name of the
|
||||
interface where the membership exists.
|
||||
.Pp
|
||||
The
|
||||
.Li ifma_addr
|
||||
.Va ifma_addr
|
||||
references the address that this membership is for.
|
||||
.Pp
|
||||
The
|
||||
.Li ifma_lladdr
|
||||
.Va ifma_lladdr
|
||||
field references a link-layer translation for the protocol-level address in
|
||||
.Li ifma_addr ,
|
||||
if one is set, otherwise it is NULL.
|
||||
.Va ifma_addr ,
|
||||
if one is set, otherwise it is
|
||||
.Dv NULL .
|
||||
.Pp
|
||||
The data returned by
|
||||
.Fn getifmaddrs
|
||||
@ -93,20 +97,20 @@ or
|
||||
.Xr sysctl 3 .
|
||||
.Sh BUGS
|
||||
If both
|
||||
.Aq Pa net/if.h
|
||||
.In net/if.h
|
||||
and
|
||||
.Aq Pa ifaddrs.h
|
||||
.In ifaddrs.h
|
||||
are being included,
|
||||
.Aq Pa net/if.h
|
||||
.In net/if.h
|
||||
.Em must
|
||||
be included before
|
||||
.Aq Pa ifaddrs.h .
|
||||
.In ifaddrs.h .
|
||||
.Sh SEE ALSO
|
||||
.Xr sysctl 3 ,
|
||||
.Xr networking 4 ,
|
||||
.Xr ifconfig 8
|
||||
.Sh HISTORY
|
||||
The
|
||||
.Nm
|
||||
implementation first appeared in
|
||||
.Fn getifmaddrs
|
||||
function first appeared in
|
||||
.Fx 5.2 .
|
||||
|
||||
@ -66,108 +66,129 @@ complicated.
|
||||
The advanced API therefore defines a set
|
||||
of functions to help applications.
|
||||
These functions assume the
|
||||
formatting rules specified in Appendix B in RFC2460 i.e., that the
|
||||
formatting rules specified in Appendix B in RFC2460, i.e., that the
|
||||
largest field is placed last in the option.
|
||||
The function prototypes for
|
||||
these functions are all in the
|
||||
.Aq Li netinet/in.h
|
||||
.In netinet/in.h
|
||||
header.
|
||||
.\"
|
||||
.Ss inet6_opt_init
|
||||
The
|
||||
.Fn inet6_opt_init
|
||||
function
|
||||
returns the number of bytes needed for the empty
|
||||
extension header i.e., without any options.
|
||||
extension header, i.e., without any options.
|
||||
If
|
||||
.Li extbuf
|
||||
is not NULL it also initializes the extension header to have the correct length
|
||||
.Va extbuf
|
||||
is not
|
||||
.Dv NULL
|
||||
it also initializes the extension header to have the correct length
|
||||
field.
|
||||
In that case if the
|
||||
.Li extlen value is not a positive
|
||||
.Po
|
||||
i.e., non-zero
|
||||
.Pc
|
||||
multiple of 8 the function fails and returns -1.
|
||||
.Fa extlen
|
||||
value is not a positive
|
||||
(i.e., non-zero)
|
||||
multiple of 8 the function fails and returns \-1.
|
||||
.\"
|
||||
.Ss inet6_opt_append
|
||||
The
|
||||
.Fn inet6_opt_append
|
||||
function
|
||||
returns the updated total length taking into account
|
||||
adding an option with length
|
||||
.Li len
|
||||
.Fa len
|
||||
and alignment
|
||||
.Li align .
|
||||
.Li Offset
|
||||
.Fa align .
|
||||
The
|
||||
.Fa offset
|
||||
argument
|
||||
should be the length returned by
|
||||
.Fn inet6_opt_init
|
||||
or a previous
|
||||
.Fn inet6_opt_append .
|
||||
If
|
||||
.Li extbuf
|
||||
is not NULL then, in addition to returning the length,
|
||||
.Fa extbuf
|
||||
is not
|
||||
.Dv NULL
|
||||
then, in addition to returning the length,
|
||||
the function inserts any needed pad option, initializes the option
|
||||
.Po
|
||||
setting the type and length fields
|
||||
.Pc
|
||||
(setting the type and length fields)
|
||||
and returns a pointer to the location for the option content in
|
||||
.Li databufp .
|
||||
.Fa databufp .
|
||||
.Pp
|
||||
.Li type
|
||||
The
|
||||
.Fa type
|
||||
argument
|
||||
is the 8-bit option type.
|
||||
.Li len
|
||||
The
|
||||
.Fa len
|
||||
argument
|
||||
is the length of the option data
|
||||
.Po
|
||||
i.e., excluding the option type and option length fields.
|
||||
.Pc
|
||||
(i.e., excluding the option type and option length fields).
|
||||
.Pp
|
||||
Once
|
||||
.Fn inet6_opt_append
|
||||
has been called the application can use the
|
||||
has been called, the application can use the
|
||||
databuf directly, or use
|
||||
.Fn inet6_opt_set_val
|
||||
to specify the content of the option.
|
||||
.Pp
|
||||
The option type must have a value from 2 to 255, inclusive.
|
||||
.Po
|
||||
0 and 1 are reserved for the Pad1 and PadN options, respectively.
|
||||
.Pc
|
||||
(0 and 1 are reserved for the Pad1 and PadN options, respectively.)
|
||||
.Pp
|
||||
The option data length must have a value between 0 and 255,
|
||||
inclusive, and is the length of the option data that follows.
|
||||
.Pp
|
||||
The
|
||||
.Li align
|
||||
.Fa align
|
||||
parameter must have a value of 1, 2, 4, or 8.
|
||||
The align value can not exceed the value of
|
||||
.Li len .
|
||||
.Fa len .
|
||||
.\"
|
||||
.Ss inet6_opt_finish
|
||||
The
|
||||
.Fn inet6_opt_finish
|
||||
function
|
||||
returns the updated total length
|
||||
taking into account the final padding of the extension header to make
|
||||
it a multiple of 8 bytes.
|
||||
.Li Offset
|
||||
The
|
||||
.Fa offset
|
||||
argument
|
||||
should be the length returned by
|
||||
.Fn inet6_opt_init
|
||||
or
|
||||
.Fn inet6_opt_append .
|
||||
If
|
||||
.Li extbuf
|
||||
is not NULL the function also
|
||||
.Fa extbuf
|
||||
is not
|
||||
.Dv NULL
|
||||
the function also
|
||||
initializes the option by inserting a Pad1 or PadN option of the
|
||||
proper length.
|
||||
.Pp
|
||||
If the necessary pad does not fit in the extension header buffer the
|
||||
function returns -1.
|
||||
function returns \-1.
|
||||
.\"
|
||||
.Ss inet6_opt_set_val
|
||||
The
|
||||
.Fn inet6_opt_set_val
|
||||
function
|
||||
inserts data items of various sizes in the data portion of the option.
|
||||
.Li Databuf
|
||||
The
|
||||
.Fa databuf
|
||||
argument
|
||||
should be a pointer returned by
|
||||
.Fn inet6_opt_append .
|
||||
.Li val
|
||||
The
|
||||
.Fa val
|
||||
argument
|
||||
should point to the data to be
|
||||
inserted.
|
||||
.Li Offset
|
||||
The
|
||||
.Fa offset
|
||||
argument
|
||||
specifies where in the data portion of the option
|
||||
the value should be inserted; the first byte after the option type
|
||||
and length is accessed by specifying an offset of zero.
|
||||
@ -179,24 +200,27 @@ Even when the alignment requirement is not satisfied,
|
||||
the function should just copy the data as required.
|
||||
.Pp
|
||||
The function returns the offset for the next field
|
||||
.Po
|
||||
i.e.,
|
||||
.Li offset
|
||||
(i.e.,
|
||||
.Fa offset
|
||||
+
|
||||
.Li vallen
|
||||
.Pc
|
||||
.Fa vallen )
|
||||
which can be used when composing option content with multiple fields.
|
||||
.\"
|
||||
.Ss inet6_opt_next
|
||||
The
|
||||
.Fn inet6_opt_next
|
||||
function
|
||||
parses received extension headers returning the next
|
||||
option.
|
||||
.Li Extbuf
|
||||
The
|
||||
.Fa extbuf
|
||||
and
|
||||
.Li extlen
|
||||
specifies the extension header.
|
||||
.Li Offset
|
||||
should either be zero (for the first option) or the length returned
|
||||
.Fa extlen
|
||||
arguments specify the extension header.
|
||||
The
|
||||
.Fa offset
|
||||
argument
|
||||
should either be zero (for the first option), or the length returned
|
||||
by a previous call to
|
||||
.Fn inet6_opt_next
|
||||
or
|
||||
@ -204,10 +228,9 @@ or
|
||||
It specifies the position where to continue scanning the extension
|
||||
buffer.
|
||||
The next option is returned by updating
|
||||
.Li typep ,
|
||||
.Li lenp ,
|
||||
.Fa typep , lenp ,
|
||||
and
|
||||
.Li databufp .
|
||||
.Fa databufp .
|
||||
This function returns the updated
|
||||
.Dq previous
|
||||
length
|
||||
@ -217,20 +240,27 @@ This returned
|
||||
length can then be passed to subsequent calls to
|
||||
.Fn inet6_opt_next .
|
||||
This function does not return any PAD1 or PADN options.
|
||||
When there are no more options the return value is -1.
|
||||
When there are no more options the return value is \-1.
|
||||
.\"
|
||||
.Ss inet6_opt_get_val
|
||||
The
|
||||
.Fn inet6_opt_get_val
|
||||
This function extracts data items of various sizes
|
||||
function extracts data items of various sizes
|
||||
in the data portion of the option.
|
||||
.Li Databuf
|
||||
The
|
||||
.Fa databuf
|
||||
argument
|
||||
should be a pointer returned by
|
||||
.Fn inet6_opt_next
|
||||
or
|
||||
.Fn inet6_opt_find .
|
||||
.Li Val
|
||||
The
|
||||
.Fa val
|
||||
argument
|
||||
should point to the destination for the extracted data.
|
||||
.Li Offset
|
||||
The
|
||||
.Fa offset
|
||||
argument
|
||||
specifies from where in the data portion of the option the value should be
|
||||
extracted; the first byte after the option type and length is
|
||||
accessed by specifying an offset of zero.
|
||||
@ -240,12 +270,10 @@ as described in Appendix B of RFC2460, but the function must not
|
||||
rely on the alignment.
|
||||
.Pp
|
||||
The function returns the offset for the next field
|
||||
.Po
|
||||
i.e.,
|
||||
.Li offset
|
||||
(i.e.,
|
||||
.Fa offset
|
||||
+
|
||||
.Li vallen
|
||||
.Pc
|
||||
.Fa vallen )
|
||||
which can be used when extracting option content with
|
||||
multiple fields.
|
||||
Robust receivers might want to verify alignment before calling
|
||||
@ -253,7 +281,7 @@ this function.
|
||||
.\"
|
||||
.Sh DIAGNOSTICS
|
||||
All the functions return
|
||||
.Li -1
|
||||
\-1
|
||||
on an error.
|
||||
.\"
|
||||
.Sh EXAMPLES
|
||||
|
||||
@ -34,11 +34,11 @@
|
||||
.Os
|
||||
.\"
|
||||
.Sh NAME
|
||||
.Nm inet6_rth_space
|
||||
.Nm inet6_rth_init
|
||||
.Nm inet6_rth_add
|
||||
.Nm inet6_rth_reverse
|
||||
.Nm inet6_rth_segments
|
||||
.Nm inet6_rth_space ,
|
||||
.Nm inet6_rth_init ,
|
||||
.Nm inet6_rth_add ,
|
||||
.Nm inet6_rth_reverse ,
|
||||
.Nm inet6_rth_segments ,
|
||||
.Nm inet6_rth_getaddr
|
||||
.Nd IPv6 Routing Header Options manipulation
|
||||
.\"
|
||||
@ -86,137 +86,157 @@ fetches one address from a Routing header
|
||||
.Pp
|
||||
The function prototypes for these functions are defined as a result
|
||||
of including the
|
||||
.Aq Li netinet/in.h
|
||||
.In netinet/in.h
|
||||
header.
|
||||
.\"
|
||||
.Ss inet6_rth_space
|
||||
The
|
||||
.Fn inet6_rth_space
|
||||
function
|
||||
returns the number of bytes required to hold a Routing
|
||||
header of the specified type containing the specified number of
|
||||
.Li segments
|
||||
.Po addresses.
|
||||
.Pc
|
||||
segments (addresses).
|
||||
For an IPv6 Type 0 Routing header, the number
|
||||
of
|
||||
.Li segments
|
||||
segments
|
||||
must be between 0 and 127, inclusive.
|
||||
The return value is just the space for the Routing header.
|
||||
When the application uses
|
||||
ancillary data it must pass the returned length to
|
||||
.Fn CMSG_LEN
|
||||
to determine how much memory is needed for the ancillary data object
|
||||
.Po
|
||||
including the cmsghdr structure.
|
||||
.Pc
|
||||
(including the
|
||||
.Vt cmsghdr
|
||||
structure).
|
||||
.Pp
|
||||
If the return value is 0, then either the type of the Routing header
|
||||
is not supported by this implementation or the number of segments is
|
||||
invalid for this type of Routing header.
|
||||
.Pp
|
||||
Note: This function returns the size but does not allocate the space
|
||||
Note: this function returns the size but does not allocate the space
|
||||
required for the ancillary data.
|
||||
This allows an application to
|
||||
allocate a larger buffer, if other ancillary data objects are
|
||||
desired, since all the ancillary data objects must be specified to
|
||||
.Fn sendmsg
|
||||
.Xr sendmsg 2
|
||||
as a single msg_control buffer.
|
||||
.Ss inet6_rth_init
|
||||
The
|
||||
.Fn inet6_rth_init
|
||||
function
|
||||
initializes the buffer pointed to by
|
||||
.Li bp
|
||||
.Fa bp
|
||||
to contain a
|
||||
Routing header of the specified type and sets ip6r_len based on the
|
||||
.Li segments
|
||||
Routing header of the specified type and sets
|
||||
.Va ip6r_len
|
||||
based on the
|
||||
.Fa segments
|
||||
parameter.
|
||||
.Li bp_len
|
||||
The
|
||||
.Fa bp_len
|
||||
argument
|
||||
is only used to verify that the buffer is
|
||||
large enough.
|
||||
The ip6r_segleft field is set to zero;
|
||||
The
|
||||
.Va ip6r_segleft
|
||||
field is set to zero;
|
||||
.Fn inet6_rth_add
|
||||
will increment it.
|
||||
.Pp
|
||||
When the application uses ancillary data the application must
|
||||
initialize any cmsghdr fields.
|
||||
initialize any
|
||||
.Vt cmsghdr
|
||||
fields.
|
||||
.Pp
|
||||
The caller must allocate the buffer and its size can be determined by
|
||||
calling
|
||||
.Fn inet6_rth_space .
|
||||
.Pp
|
||||
Upon success the return value is the pointer to the buffer
|
||||
.Li bp ,
|
||||
.Fa bp ,
|
||||
and this is then used as the first argument to the next two functions.
|
||||
Upon an error the return value is NULL.
|
||||
Upon an error the return value is
|
||||
.Dv NULL .
|
||||
.\"
|
||||
.Ss inet6_rth_add
|
||||
The
|
||||
.Fn inet6_rth_add
|
||||
function
|
||||
adds the IPv6 address pointed to by
|
||||
.Li addr
|
||||
.Fa addr
|
||||
to the end of the Routing header being constructed.
|
||||
.Pp
|
||||
If successful, the segleft member of the Routing Header is updated to
|
||||
If successful, the
|
||||
.Va segleft
|
||||
member of the Routing Header is updated to
|
||||
account for the new address in the Routing header and the return
|
||||
value of the function is 0.
|
||||
Upon an error the return value of the function is -1.
|
||||
Upon an error the return value of the function is \-1.
|
||||
.\"
|
||||
.Ss inet6_rth_reverse
|
||||
The
|
||||
.Fn inet6_rth_reverse
|
||||
function
|
||||
takes a Routing header extension header
|
||||
.Po
|
||||
pointed to by the first argument
|
||||
.Li in
|
||||
.Pc
|
||||
(pointed to by the first argument
|
||||
.Fa in )
|
||||
and writes a new Routing header that sends
|
||||
datagrams along the reverse of that route.
|
||||
Both arguments are allowed to point to the same buffer
|
||||
.Po
|
||||
that is, the reversal can occur in place.
|
||||
.Pc
|
||||
(that is, the reversal can occur in place).
|
||||
.Pp
|
||||
The return value of the function is 0 on success, or -1 upon an error.
|
||||
The return value of the function is 0 on success, or \-1 upon an error.
|
||||
.\"
|
||||
.Ss inet6_rth_segments
|
||||
The
|
||||
.Fn inet6_rth_segments
|
||||
function
|
||||
returns the number of segments
|
||||
.Po
|
||||
addresses
|
||||
.Pc
|
||||
(addresses)
|
||||
contained in the Routing header described by
|
||||
.Li bp .
|
||||
.Fa bp .
|
||||
On success the return value is
|
||||
zero or greater.
|
||||
The return value of the function is -1 upon an error.
|
||||
The return value of the function is \-1 upon an error.
|
||||
.\"
|
||||
.Ss inet6_rth_getaddr
|
||||
The
|
||||
.Fn inet6_rth_getaddr
|
||||
function
|
||||
returns a pointer to the IPv6 address specified by
|
||||
.Li index
|
||||
.Po
|
||||
which must have a value between 0 and one less than the value
|
||||
.Fa index
|
||||
(which must have a value between 0 and one less than the value
|
||||
returned by
|
||||
.Fn inet6_rth_segments
|
||||
.Pc
|
||||
.Fn inet6_rth_segments )
|
||||
in the Routing header described by
|
||||
.Li bp .
|
||||
.Fa bp .
|
||||
An application should first call
|
||||
.Fn inet6_rth_segments
|
||||
to obtain the number of segments in the Routing header.
|
||||
.Pp
|
||||
Upon an error the return value of the function is NULL.
|
||||
Upon an error the return value of the function is
|
||||
.Dv NULL .
|
||||
.\"
|
||||
.Sh DIAGNOSTICS
|
||||
The
|
||||
.Fn inet6_rth_space
|
||||
and
|
||||
.FN inet6_rth_getaddr
|
||||
.Fn inet6_rth_getaddr
|
||||
functions
|
||||
return 0 on errors.
|
||||
.Pp
|
||||
The
|
||||
.Fn inet6_rthdr_init
|
||||
function
|
||||
returns
|
||||
.Dv NULL
|
||||
on error.
|
||||
The
|
||||
.Fn inet6_rth_add
|
||||
and
|
||||
.Fn inet6_rth_reverse
|
||||
return0 on success, or -1 upon an error.
|
||||
functions
|
||||
return 0 on success, or \-1 upon an error.
|
||||
.\"
|
||||
.Sh EXAMPLES
|
||||
draft-ietf-ipngwg-rfc2292bis-08.txt
|
||||
|
||||
Loading…
Reference in New Issue
Block a user