.\" $OpenBSD: byteorder.3,v 1.8 2000/04/18 03:01:30 aaron Exp $
|
.\" $OpenBSD: byteorder.3,v 1.8 2000/04/18 03:01:30 aaron Exp $
|
.\"
|
.\"
|
.\" Copyright (c) 1983, 1991, 1993
|
.\" Copyright (c) 1983, 1991, 1993
|
.\" The Regents of the University of California. All rights reserved.
|
.\" The Regents of the University of California. All rights reserved.
|
.\"
|
.\"
|
.\" Redistribution and use in source and binary forms, with or without
|
.\" Redistribution and use in source and binary forms, with or without
|
.\" modification, are permitted provided that the following conditions
|
.\" modification, are permitted provided that the following conditions
|
.\" are met:
|
.\" are met:
|
.\" 1. Redistributions of source code must retain the above copyright
|
.\" 1. Redistributions of source code must retain the above copyright
|
.\" notice, this list of conditions and the following disclaimer.
|
.\" notice, this list of conditions and the following disclaimer.
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
.\" notice, this list of conditions and the following disclaimer in the
|
.\" notice, this list of conditions and the following disclaimer in the
|
.\" documentation and/or other materials provided with the distribution.
|
.\" documentation and/or other materials provided with the distribution.
|
.\" 3. All advertising materials mentioning features or use of this software
|
.\" 3. All advertising materials mentioning features or use of this software
|
.\" must display the following acknowledgement:
|
.\" must display the following acknowledgement:
|
.\" This product includes software developed by the University of
|
.\" This product includes software developed by the University of
|
.\" California, Berkeley and its contributors.
|
.\" California, Berkeley and its contributors.
|
.\" 4. Neither the name of the University nor the names of its contributors
|
.\" 4. Neither the name of the University nor the names of its contributors
|
.\" may be used to endorse or promote products derived from this software
|
.\" may be used to endorse or promote products derived from this software
|
.\" without specific prior written permission.
|
.\" without specific prior written permission.
|
.\"
|
.\"
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
.\" 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
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
.\" SUCH DAMAGE.
|
.\" SUCH DAMAGE.
|
.\"
|
.\"
|
.Dd June 4, 1993
|
.Dd June 4, 1993
|
.Dt BYTEORDER 3
|
.Dt BYTEORDER 3
|
.Os
|
.Os
|
.Sh NAME
|
.Sh NAME
|
.Nm htonl ,
|
.Nm htonl ,
|
.Nm htons ,
|
.Nm htons ,
|
.Nm ntohl ,
|
.Nm ntohl ,
|
.Nm ntohs ,
|
.Nm ntohs ,
|
.Nm htobe32 ,
|
.Nm htobe32 ,
|
.Nm htobe16 ,
|
.Nm htobe16 ,
|
.Nm betoh32 ,
|
.Nm betoh32 ,
|
.Nm betoh16 ,
|
.Nm betoh16 ,
|
.Nm htole32 ,
|
.Nm htole32 ,
|
.Nm htole16 ,
|
.Nm htole16 ,
|
.Nm letoh32 ,
|
.Nm letoh32 ,
|
.Nm letoh16 ,
|
.Nm letoh16 ,
|
.Nm swap32 ,
|
.Nm swap32 ,
|
.Nm swap16
|
.Nm swap16
|
.Nd convert values between different byte orderings
|
.Nd convert values between different byte orderings
|
.Sh SYNOPSIS
|
.Sh SYNOPSIS
|
.Fd #include
|
.Fd #include
|
.Fd #include
|
.Fd #include
|
.Ft u_int32_t
|
.Ft u_int32_t
|
.Fn htonl "u_int32_t host32"
|
.Fn htonl "u_int32_t host32"
|
.Ft u_int16_t
|
.Ft u_int16_t
|
.Fn htons "u_int16_t host16"
|
.Fn htons "u_int16_t host16"
|
.Ft u_int32_t
|
.Ft u_int32_t
|
.Fn ntohl "u_int32_t net32"
|
.Fn ntohl "u_int32_t net32"
|
.Ft u_int16_t
|
.Ft u_int16_t
|
.Fn ntohs "u_int16_t net16"
|
.Fn ntohs "u_int16_t net16"
|
.Ft u_int32_t
|
.Ft u_int32_t
|
.Fn htobe32 "u_int32_t host32"
|
.Fn htobe32 "u_int32_t host32"
|
.Ft u_int16_t
|
.Ft u_int16_t
|
.Fn htobe16 "u_int16_t host16"
|
.Fn htobe16 "u_int16_t host16"
|
.Ft u_int32_t
|
.Ft u_int32_t
|
.Fn betoh32 "u_int32_t big32"
|
.Fn betoh32 "u_int32_t big32"
|
.Ft u_int16_t
|
.Ft u_int16_t
|
.Fn betoh16 "u_int16_t big16"
|
.Fn betoh16 "u_int16_t big16"
|
.Ft u_int32_t
|
.Ft u_int32_t
|
.Fn htole32 "u_int32_t host32"
|
.Fn htole32 "u_int32_t host32"
|
.Ft u_int16_t
|
.Ft u_int16_t
|
.Fn htole16 "u_int16_t host16"
|
.Fn htole16 "u_int16_t host16"
|
.Ft u_int32_t
|
.Ft u_int32_t
|
.Fn letoh32 "u_int32_t little32"
|
.Fn letoh32 "u_int32_t little32"
|
.Ft u_int16_t
|
.Ft u_int16_t
|
.Fn letoh16 "u_int16_t little16"
|
.Fn letoh16 "u_int16_t little16"
|
.Ft u_int32_t
|
.Ft u_int32_t
|
.Fn swap32 "u_int32_t val32"
|
.Fn swap32 "u_int32_t val32"
|
.Ft u_int16_t
|
.Ft u_int16_t
|
.Fn swap16 "u_int16_t val16"
|
.Fn swap16 "u_int16_t val16"
|
.Sh DESCRIPTION
|
.Sh DESCRIPTION
|
These routines convert 16- and 32-bit quantities between different
|
These routines convert 16- and 32-bit quantities between different
|
byte orderings.
|
byte orderings.
|
The
|
The
|
.Dq swap
|
.Dq swap
|
functions reverse the byte ordering of
|
functions reverse the byte ordering of
|
the given quantity, the others converts either from/to the native
|
the given quantity, the others converts either from/to the native
|
byte order used by the host to/from either little- or big-endian (a.k.a
|
byte order used by the host to/from either little- or big-endian (a.k.a
|
network) order.
|
network) order.
|
.Pp
|
.Pp
|
Apart from the swap functions, the names can be described by this form:
|
Apart from the swap functions, the names can be described by this form:
|
{src-order}to{dst-order}{size}.
|
{src-order}to{dst-order}{size}.
|
Both {src-order} and {dst-order} can take the following forms:
|
Both {src-order} and {dst-order} can take the following forms:
|
.Pp
|
.Pp
|
.Bl -tag -width "be " -offset indent -compact
|
.Bl -tag -width "be " -offset indent -compact
|
.It h
|
.It h
|
Host order.
|
Host order.
|
.It n
|
.It n
|
Network order (big-endian).
|
Network order (big-endian).
|
.It be
|
.It be
|
Big-endian (most significant byte first).
|
Big-endian (most significant byte first).
|
.It le
|
.It le
|
Little-endian (least significant byte first).
|
Little-endian (least significant byte first).
|
.El
|
.El
|
.Pp
|
.Pp
|
One of the specified orderings must be
|
One of the specified orderings must be
|
.Sq h .
|
.Sq h .
|
{size} will take these forms:
|
{size} will take these forms:
|
.Pp
|
.Pp
|
.Bl -tag -width "32 " -offset indent -compact
|
.Bl -tag -width "32 " -offset indent -compact
|
.It l
|
.It l
|
Long (32-bit, used in conjunction with forms involving
|
Long (32-bit, used in conjunction with forms involving
|
.Sq n ) .
|
.Sq n ) .
|
.It s
|
.It s
|
Short (16-bit, used in conjunction with forms involving
|
Short (16-bit, used in conjunction with forms involving
|
.Sq n ) .
|
.Sq n ) .
|
.It 16
|
.It 16
|
16-bit.
|
16-bit.
|
.It 32
|
.It 32
|
32-bit.
|
32-bit.
|
.El
|
.El
|
.Pp
|
.Pp
|
The swap functions are of the form: swap{size}.
|
The swap functions are of the form: swap{size}.
|
.Pp
|
.Pp
|
Names involving
|
Names involving
|
.Sq n
|
.Sq n
|
convert quantities between network
|
convert quantities between network
|
byte order and host byte order.
|
byte order and host byte order.
|
The last letter
|
The last letter
|
.Pf ( Sq s
|
.Pf ( Sq s
|
or
|
or
|
.Sq l )
|
.Sq l )
|
is a mnemonic
|
is a mnemonic
|
for the traditional names for such quantities,
|
for the traditional names for such quantities,
|
.Li short
|
.Li short
|
and
|
and
|
.Li long ,
|
.Li long ,
|
respectively.
|
respectively.
|
Today, the C concept of
|
Today, the C concept of
|
.Li short
|
.Li short
|
and
|
and
|
.Li long
|
.Li long
|
integers need not coincide with this traditional misunderstanding.
|
integers need not coincide with this traditional misunderstanding.
|
On machines which have a byte order which is the same as the network
|
On machines which have a byte order which is the same as the network
|
order, routines are defined as null macros.
|
order, routines are defined as null macros.
|
.Pp
|
.Pp
|
The functions involving either
|
The functions involving either
|
.Dq be ,
|
.Dq be ,
|
.Dq le ,
|
.Dq le ,
|
or
|
or
|
.Dq swap
|
.Dq swap
|
use the numbers
|
use the numbers
|
16 and 32 for specifying the bitwidth of the quantities they operate on.
|
16 and 32 for specifying the bitwidth of the quantities they operate on.
|
Currently all supported architectures are either big- or little-endian
|
Currently all supported architectures are either big- or little-endian
|
so either the
|
so either the
|
.Dq be
|
.Dq be
|
or
|
or
|
.Dq le
|
.Dq le
|
variants are implemented as null macros.
|
variants are implemented as null macros.
|
.Pp
|
.Pp
|
The routines mentioned above which have either {src-order} or {dst-order}
|
The routines mentioned above which have either {src-order} or {dst-order}
|
set to
|
set to
|
.Sq n
|
.Sq n
|
are most often used in
|
are most often used in
|
conjunction with Internet addresses and ports as returned by
|
conjunction with Internet addresses and ports as returned by
|
.Xr gethostbyname 3
|
.Xr gethostbyname 3
|
and
|
and
|
.Xr getservent 3 .
|
.Xr getservent 3 .
|
.Sh SEE ALSO
|
.Sh SEE ALSO
|
.Xr gethostbyname 3 ,
|
.Xr gethostbyname 3 ,
|
.Xr getservent 3
|
.Xr getservent 3
|
.Sh HISTORY
|
.Sh HISTORY
|
The
|
The
|
.Nm byteorder
|
.Nm byteorder
|
functions appeared in
|
functions appeared in
|
.Bx 4.2 .
|
.Bx 4.2 .
|
.Sh BUGS
|
.Sh BUGS
|
On the vax, alpha, i386, and so far mips,
|
On the vax, alpha, i386, and so far mips,
|
bytes are handled backwards from most everyone else in the world.
|
bytes are handled backwards from most everyone else in the world.
|
This is not expected to be fixed in the near future.
|
This is not expected to be fixed in the near future.
|
|
|
