manual: Update struct sockaddr_in, struct sockaddr_sin6 description

Message ID 87a7jgd7yd.fsf@oldenburg2.str.redhat.com
State New
Headers show
Series
  • manual: Update struct sockaddr_in, struct sockaddr_sin6 description
Related show

Commit Message

Florian Weimer Jan. 31, 2019, 5:59 p.m.
Clarify the byte order of the the struct fields and document
sin6_flowinfo and sin6_scope_id.

2019-01-31  Florian Weimer  <fweimer@redhat.com>

	* manual/socket.texi (Internet Address Formats): Clarify the byte
	order of struct sockaddr_in, struct sockaddr_in6.  Document
	sin6_flowinfo and sin6_scope_id.

Comments

Adhemerval Zanella Feb. 1, 2019, 11:47 a.m. | #1
On 31/01/2019 15:59, Florian Weimer wrote:
> Clarify the byte order of the the struct fields and document
> sin6_flowinfo and sin6_scope_id.
> 
> 2019-01-31  Florian Weimer  <fweimer@redhat.com>
> 
> 	* manual/socket.texi (Internet Address Formats): Clarify the byte
> 	order of struct sockaddr_in, struct sockaddr_in6.  Document
> 	sin6_flowinfo and sin6_scope_id.

LGTM.

> 
> diff --git a/manual/socket.texi b/manual/socket.texi
> index a6c44b77c3..cd7c0e7b12 100644
> --- a/manual/socket.texi
> +++ b/manual/socket.texi
> @@ -779,16 +779,17 @@ Internet namespace.  It has the following members:
>  @table @code
>  @item sa_family_t sin_family
>  This identifies the address family or format of the socket address.
> -You should store the value @code{AF_INET} in this member.
> -@xref{Socket Addresses}.
> +You should store the value @code{AF_INET} in this member.  The address
> +family is stored in host byte order.  @xref{Socket Addresses}.
>  
>  @item struct in_addr sin_addr
> -This is the Internet address of the host machine.  @xref{Host
> -Addresses}, and @ref{Host Names}, for how to get a value to store
> -here.
> +This is the IPv4 address.  @xref{Host Addresses}, and @ref{Host
> +Names}, for how to get a value to store here.  The IPv4 address is
> +stored in network byte order.
>  
>  @item unsigned short int sin_port
> -This is the port number.  @xref{Ports}.
> +This is the port number.  @xref{Ports}.  The port number is stored in
> +network byte order.
>  @end table
>  @end deftp
>  
> @@ -804,18 +805,36 @@ namespace.  It has the following members:
>  @item sa_family_t sin6_family
>  This identifies the address family or format of the socket address.
>  You should store the value of @code{AF_INET6} in this member.
> -@xref{Socket Addresses}.
> +@xref{Socket Addresses}.  The address family is stored in host byte
> +order.
>  
>  @item struct in6_addr sin6_addr
>  This is the IPv6 address of the host machine.  @xref{Host
>  Addresses}, and @ref{Host Names}, for how to get a value to store
> -here.
> +here.  The address is stored in network byte order.
>  
>  @item uint32_t sin6_flowinfo
> -This is a currently unimplemented field.
> +@cindex flow label
> +@cindex IPv6 flow label
> +@cindex traffic class
> +@cindex IPv6 traffic class
> +This combines the IPv6 traffic class and flow label values, as found
> +in the IPv6 header.  This field is stored in network byte order.  Only
> +the 28 lower bits (of the number in network byte order) are used; the
> +remainig bits must be zero.  The lower 20 bits are the flow label, and
> +bits 20 to 27 are the the traffic class.  Typically, this field is
> +zero.
> +
> +@item uint32_t sin6_scope_id
> +@cindex scope ID
> +@cindex IPv6 scope ID
> +For link-local addresses, this identifies the interface on which this
> +address is valid.  The scope ID is stored in host byte order.
> +Typically, this field is zero.
>  
>  @item uint16_t sin6_port
> -This is the port number.  @xref{Ports}.
> +This is the port number.  @xref{Ports}.  The port number is stored in
> +network byte order.
>  
>  @end table
>  @end deftp
>

Patch

diff --git a/manual/socket.texi b/manual/socket.texi
index a6c44b77c3..cd7c0e7b12 100644
--- a/manual/socket.texi
+++ b/manual/socket.texi
@@ -779,16 +779,17 @@  Internet namespace.  It has the following members:
 @table @code
 @item sa_family_t sin_family
 This identifies the address family or format of the socket address.
-You should store the value @code{AF_INET} in this member.
-@xref{Socket Addresses}.
+You should store the value @code{AF_INET} in this member.  The address
+family is stored in host byte order.  @xref{Socket Addresses}.
 
 @item struct in_addr sin_addr
-This is the Internet address of the host machine.  @xref{Host
-Addresses}, and @ref{Host Names}, for how to get a value to store
-here.
+This is the IPv4 address.  @xref{Host Addresses}, and @ref{Host
+Names}, for how to get a value to store here.  The IPv4 address is
+stored in network byte order.
 
 @item unsigned short int sin_port
-This is the port number.  @xref{Ports}.
+This is the port number.  @xref{Ports}.  The port number is stored in
+network byte order.
 @end table
 @end deftp
 
@@ -804,18 +805,36 @@  namespace.  It has the following members:
 @item sa_family_t sin6_family
 This identifies the address family or format of the socket address.
 You should store the value of @code{AF_INET6} in this member.
-@xref{Socket Addresses}.
+@xref{Socket Addresses}.  The address family is stored in host byte
+order.
 
 @item struct in6_addr sin6_addr
 This is the IPv6 address of the host machine.  @xref{Host
 Addresses}, and @ref{Host Names}, for how to get a value to store
-here.
+here.  The address is stored in network byte order.
 
 @item uint32_t sin6_flowinfo
-This is a currently unimplemented field.
+@cindex flow label
+@cindex IPv6 flow label
+@cindex traffic class
+@cindex IPv6 traffic class
+This combines the IPv6 traffic class and flow label values, as found
+in the IPv6 header.  This field is stored in network byte order.  Only
+the 28 lower bits (of the number in network byte order) are used; the
+remainig bits must be zero.  The lower 20 bits are the flow label, and
+bits 20 to 27 are the the traffic class.  Typically, this field is
+zero.
+
+@item uint32_t sin6_scope_id
+@cindex scope ID
+@cindex IPv6 scope ID
+For link-local addresses, this identifies the interface on which this
+address is valid.  The scope ID is stored in host byte order.
+Typically, this field is zero.
 
 @item uint16_t sin6_port
-This is the port number.  @xref{Ports}.
+This is the port number.  @xref{Ports}.  The port number is stored in
+network byte order.
 
 @end table
 @end deftp