svn commit: r52177 - head/en_US.ISO8859-1/books/developers-handbook/sockets
Benedict Reuschling
bcr at FreeBSD.org
Sun Aug 26 18:34:51 UTC 2018
Author: bcr
Date: Sun Aug 26 18:34:50 2018
New Revision: 52177
URL: https://svnweb.freebsd.org/changeset/doc/52177
Log:
Correct errors reported by textproc/igor:
- wrap long lines
- add two spaces after a sentence stop
- use tabs instead of spaces
- bad tag indent
Modified:
head/en_US.ISO8859-1/books/developers-handbook/sockets/chapter.xml
Modified: head/en_US.ISO8859-1/books/developers-handbook/sockets/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/developers-handbook/sockets/chapter.xml Sun Aug 26 15:56:45 2018 (r52176)
+++ head/en_US.ISO8859-1/books/developers-handbook/sockets/chapter.xml Sun Aug 26 18:34:50 2018 (r52177)
@@ -4,29 +4,37 @@
$FreeBSD$
-->
-<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sockets">
- <info><title>Sockets</title>
+<chapter xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:id="sockets">
+ <info>
+ <title>Sockets</title>
+
<authorgroup>
- <author><personname><firstname>G. Adam</firstname><surname>Stanislav</surname></personname><contrib>Contributed by </contrib></author>
+ <author>
+ <personname>
+ <firstname>G. Adam</firstname>
+ <surname>Stanislav</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
</authorgroup>
</info>
-
-
<sect1 xml:id="sockets-synopsis">
<title>Synopsis</title>
<para><acronym>BSD</acronym> sockets take interprocess
- communications to a new level. It is no longer necessary for the
- communicating processes to run on the same machine. They still
- <emphasis>can</emphasis>, but they do not have to.</para>
+ communications to a new level. It is no longer necessary for
+ the communicating processes to run on the same machine. They
+ still <emphasis>can</emphasis>, but they do not have to.</para>
<para>Not only do these processes not have to run on the same
machine, they do not have to run under the same operating
- system. Thanks to <acronym>BSD</acronym> sockets, your FreeBSD
+ system. Thanks to <acronym>BSD</acronym> sockets, your FreeBSD
software can smoothly cooperate with a program running on a
- &macintosh;, another one running on a &sun; workstation, yet another
- one running under &windows; 2000, all connected with an
+ &macintosh;, another one running on a &sun; workstation, yet
+ another one running under &windows; 2000, all connected with an
Ethernet-based local area network.</para>
<para>But your software can equally well cooperate with processes
@@ -44,40 +52,40 @@
<title>Networking and Diversity</title>
<para>We have already hinted on the <emphasis>diversity</emphasis>
- of networking. Many different systems have to talk to each
- other. And they have to speak the same language. They also have
- to <emphasis>understand</emphasis> the same language the same
- way.</para>
+ of networking. Many different systems have to talk to each
+ other. And they have to speak the same language. They also
+ have to <emphasis>understand</emphasis> the same language the
+ same way.</para>
<para>People often think that <emphasis>body language</emphasis>
- is universal. But it is not. Back in my early teens, my father
- took me to Bulgaria. We were sitting at a table in a park in
+ is universal. But it is not. Back in my early teens, my father
+ took me to Bulgaria. We were sitting at a table in a park in
Sofia, when a vendor approached us trying to sell us some
roasted almonds.</para>
<para>I had not learned much Bulgarian by then, so, instead of
saying no, I shook my head from side to side, the
<quote>universal</quote> body language for
- <emphasis>no</emphasis>. The vendor quickly started serving us
+ <emphasis>no</emphasis>. The vendor quickly started serving us
some almonds.</para>
<para>I then remembered I had been told that in Bulgaria shaking
- your head sideways meant <emphasis>yes</emphasis>. Quickly, I
- started nodding my head up and down. The vendor noticed, took
- his almonds, and walked away. To an uninformed observer, I did
+ your head sideways meant <emphasis>yes</emphasis>. Quickly, I
+ started nodding my head up and down. The vendor noticed, took
+ his almonds, and walked away. To an uninformed observer, I did
not change the body language: I continued using the language of
- shaking and nodding my head. What changed was the
- <emphasis>meaning</emphasis> of the body language. At first, the
- vendor and I interpreted the same language as having completely
- different meaning. I had to adjust my own interpretation of that
- language so the vendor would understand.</para>
+ shaking and nodding my head. What changed was the
+ <emphasis>meaning</emphasis> of the body language. At first,
+ the vendor and I interpreted the same language as having
+ completely different meaning. I had to adjust my own
+ interpretation of that language so the vendor would
+ understand.</para>
<para>It is the same with computers: The same symbols may have
- different, even outright opposite meaning. Therefore, for
- two computers to understand each other, they must not only
- agree on the same <emphasis>language</emphasis>, but on the
- same <emphasis>interpretation</emphasis> of the language.
- </para>
+ different, even outright opposite meaning. Therefore, for two
+ computers to understand each other, they must not only agree on
+ the same <emphasis>language</emphasis>, but on the same
+ <emphasis>interpretation</emphasis> of the language.</para>
</sect1>
<sect1 xml:id="sockets-protocols">
@@ -86,7 +94,7 @@
<para>While various programming languages tend to have complex
syntax and use a number of multi-letter reserved words (which
makes them easy for the human programmer to understand), the
- languages of data communications tend to be very terse. Instead
+ languages of data communications tend to be very terse. Instead
of multi-byte words, they often use individual
<emphasis>bits</emphasis>. There is a very convincing reason
for it: While data travels <emphasis>inside</emphasis> your
@@ -98,7 +106,7 @@
<emphasis>protocols</emphasis> rather than languages.</para>
<para>As data travels from one computer to another, it always uses
- more than one protocol. These protocols are
+ more than one protocol. These protocols are
<emphasis>layered</emphasis>. The data can be compared to the
inside of an onion: You have to peel off several layers of
<quote>skin</quote> to get to the data. This is best
@@ -106,11 +114,11 @@
<mediaobject>
<imageobject>
- <imagedata fileref="sockets/layers"/>
+ <imagedata fileref="sockets/layers"/>
</imageobject>
<textobject>
- <literallayout class="monospaced">+----------------+
+ <literallayout class="monospaced">+----------------+
| Ethernet |
|+--------------+|
|| IP ||
@@ -131,7 +139,7 @@
</textobject>
<textobject>
- <phrase>Protocol Layers</phrase>
+ <phrase>Protocol Layers</phrase>
</textobject>
</mediaobject>
@@ -153,7 +161,7 @@
<para>I think you get the picture...</para>
<para>To inform our software how to handle the raw data, it is
- encoded as a <acronym>PNG</acronym> file. It could be a
+ encoded as a <acronym>PNG</acronym> file. It could be a
<acronym>GIF</acronym>, or a <acronym>JPEG</acronym>, but it is
a <acronym>PNG</acronym>.</para>
@@ -161,13 +169,13 @@
<para>At this point, I can hear some of you yelling,
<emphasis><quote>No, it is not! It is a file
- format!</quote></emphasis></para>
+ format!</quote></emphasis></para>
- <para>Well, of course it is a file format. But from the
+ <para>Well, of course it is a file format. But from the
perspective of data communications, a file format is a protocol:
The file structure is a <emphasis>language</emphasis>, a terse
one at that, communicating to our <emphasis>process</emphasis>
- how the data is organized. Ergo, it is a
+ how the data is organized. Ergo, it is a
<emphasis>protocol</emphasis>.</para>
<para>Alas, if all we received was the <acronym>PNG</acronym>
@@ -179,63 +187,63 @@
<acronym>JPEG</acronym>, or some other image format?</para>
<para>To obtain that information, we are using another protocol:
- <acronym>HTTP</acronym>. This protocol can tell us exactly that
+ <acronym>HTTP</acronym>. This protocol can tell us exactly that
the data represents an image, and that it uses the
- <acronym>PNG</acronym> protocol. It can also tell us some other
- things, but let us stay focused on protocol layers here.
- </para>
+ <acronym>PNG</acronym> protocol. It can also tell us some other
+ things, but let us stay focused on protocol layers here.</para>
- <para>So, now we have some data wrapped in the <acronym>PNG</acronym>
- protocol, wrapped in the <acronym>HTTP</acronym> protocol.
- How did we get it from the server?</para>
+ <para>So, now we have some data wrapped in the
+ <acronym>PNG</acronym> protocol, wrapped in the
+ <acronym>HTTP</acronym> protocol. How did we get it from the
+ server?</para>
<para>By using <acronym>TCP/IP</acronym> over Ethernet, that is
- how. Indeed, that is three more protocols. Instead of
+ how. Indeed, that is three more protocols. Instead of
continuing inside out, I am now going to talk about Ethernet,
simply because it is easier to explain the rest that way.</para>
<para>Ethernet is an interesting system of connecting computers in
a <emphasis>local area network</emphasis>
(<acronym>LAN</acronym>). Each computer has a <emphasis>network
- interface card</emphasis> (<acronym>NIC</acronym>), which has a
- unique 48-bit <acronym>ID</acronym> called its
- <emphasis>address</emphasis>. No two Ethernet
- <acronym>NIC</acronym>s in the world have the same address.
- </para>
+ interface card</emphasis> (<acronym>NIC</acronym>), which has
+ a unique 48-bit <acronym>ID</acronym> called its
+ <emphasis>address</emphasis>. No two Ethernet
+ <acronym>NIC</acronym>s in the world have the same
+ address.</para>
<para>These <acronym>NIC</acronym>s are all connected with each
- other. Whenever one computer wants to communicate with another
+ other. Whenever one computer wants to communicate with another
in the same Ethernet <acronym>LAN</acronym>, it sends a message
- over the network. Every <acronym>NIC</acronym> sees the
- message. But as part of the Ethernet
+ over the network. Every <acronym>NIC</acronym> sees the
+ message. But as part of the Ethernet
<emphasis>protocol</emphasis>, the data contains the address of
- the destination <acronym>NIC</acronym> (among other things). So,
- only one of all the network interface cards will pay attention
- to it, the rest will ignore it.</para>
+ the destination <acronym>NIC</acronym> (among other things).
+ So, only one of all the network interface cards will pay
+ attention to it, the rest will ignore it.</para>
- <para>But not all computers are connected to the same
- network. Just because we have received the data over our
- Ethernet does not mean it originated in our own local area
- network. It could have come to us from some other network (which
- may not even be Ethernet based) connected with our own network
- via the Internet.</para>
+ <para>But not all computers are connected to the same network.
+ Just because we have received the data over our Ethernet does
+ not mean it originated in our own local area network. It could
+ have come to us from some other network (which may not even be
+ Ethernet based) connected with our own network via the
+ Internet.</para>
<para>All data is transferred over the Internet using
<acronym>IP</acronym>, which stands for <emphasis>Internet
- Protocol</emphasis>. Its basic role is to let us know where in
- the world the data has arrived from, and where it is supposed to
- go to. It does not <emphasis>guarantee</emphasis> we will
+ Protocol</emphasis>. Its basic role is to let us know where
+ in the world the data has arrived from, and where it is supposed
+ to go to. It does not <emphasis>guarantee</emphasis> we will
receive the data, only that we will know where it came from
<emphasis>if</emphasis> we do receive it.</para>
<para>Even if we do receive the data, <acronym>IP</acronym> does
not guarantee we will receive various chunks of data in the same
- order the other computer has sent it to us. So, we can receive
+ order the other computer has sent it to us. So, we can receive
the center of our image before we receive the upper left corner
and after the lower right, for example.</para>
<para>It is <acronym>TCP</acronym> (<emphasis>Transmission Control
- Protocol</emphasis>) that asks the sender to resend any lost
+ Protocol</emphasis>) that asks the sender to resend any lost
data and that places it all into the proper order.</para>
<para>All in all, it took <emphasis>five</emphasis> different
@@ -248,7 +256,7 @@
<acronym>Ethernet</acronym> protocol.</para>
<para>Oh, and by the way, there probably were several other
- protocols involved somewhere on the way. For example, if our
+ protocols involved somewhere on the way. For example, if our
<acronym>LAN</acronym> was connected to the Internet through a
dial-up call, it used the <acronym>PPP</acronym> protocol over
the modem which used one (or several) of the various modem
@@ -256,38 +264,38 @@
<para>As a developer you should be asking by now,
<emphasis><quote>How am I supposed to handle it
- all?</quote></emphasis></para>
+ all?</quote></emphasis></para>
<para>Luckily for you, you are <emphasis>not</emphasis> supposed
- to handle it all. You <emphasis>are</emphasis> supposed to
- handle some of it, but not all of it. Specifically, you need not
- worry about the physical connection (in our case Ethernet and
- possibly <acronym>PPP</acronym>, etc). Nor do you need to handle
- the Internet Protocol, or the Transmission Control
+ to handle it all. You <emphasis>are</emphasis> supposed to
+ handle some of it, but not all of it. Specifically, you need
+ not worry about the physical connection (in our case Ethernet
+ and possibly <acronym>PPP</acronym>, etc). Nor do you need to
+ handle the Internet Protocol, or the Transmission Control
Protocol.</para>
<para>In other words, you do not have to do anything to receive
- the data from the other computer. Well, you do have to
+ the data from the other computer. Well, you do have to
<emphasis>ask</emphasis> for it, but that is almost as simple as
opening a file.</para>
<para>Once you have received the data, it is up to you to figure
- out what to do with it. In our case, you would need to
+ out what to do with it. In our case, you would need to
understand the <acronym>HTTP</acronym> protocol and the
<acronym>PNG</acronym> file structure.</para>
<para>To use an analogy, all the internetworking protocols become
a gray area: Not so much because we do not understand how it
- works, but because we are no longer concerned about it. The
+ works, but because we are no longer concerned about it. The
sockets interface takes care of this gray area for us:</para>
<mediaobject>
<imageobject>
- <imagedata fileref="sockets/slayers"/>
+ <imagedata fileref="sockets/slayers"/>
</imageobject>
<textobject>
- <literallayout class="monospaced">+----------------+
+ <literallayout class="monospaced">+----------------+
|xxxxEthernetxxxx|
|+--------------+|
||xxxxxxIPxxxxxx||
@@ -308,7 +316,7 @@
</textobject>
<textobject>
- <phrase>Sockets Covered Protocol Layers</phrase>
+ <phrase>Sockets Covered Protocol Layers</phrase>
</textobject>
</mediaobject>
@@ -325,14 +333,13 @@
<para><acronym>BSD</acronym> sockets are built on the basic &unix;
model: <emphasis>Everything is a file.</emphasis> In our
example, then, sockets would let us receive an <emphasis>HTTP
- file</emphasis>, so to speak. It would then be up to us to
+ file</emphasis>, so to speak. It would then be up to us to
extract the <emphasis><acronym>PNG</acronym> file</emphasis>
- from it.
- </para>
+ from it.</para>
<para>Because of the complexity of internetworking, we cannot just
use the <function role="syscall">open</function> system call, or
- the <function>open()</function> C function. Instead, we need to
+ the <function>open()</function> C function. Instead, we need to
take several steps to <quote>opening</quote> a socket.</para>
<para>Once we do, however, we can start treating the
@@ -356,32 +363,30 @@
<title>The Client-Server Difference</title>
<para>Typically, one of the ends of a socket-based data
- communication is a <emphasis>server</emphasis>, the other is a
- <emphasis>client</emphasis>.</para>
+ communication is a <emphasis>server</emphasis>, the other is a
+ <emphasis>client</emphasis>.</para>
<sect3 xml:id="sockets-common-elements">
- <title>The Common Elements</title>
+ <title>The Common Elements</title>
- <sect4 xml:id="sockets-socket">
+ <sect4 xml:id="sockets-socket">
<title><function>socket</function></title>
<para>The one function used by both, clients and servers, is
- &man.socket.2;. It is declared this way:</para>
+ &man.socket.2;. It is declared this way:</para>
-<programlisting>
-int socket(int domain, int type, int protocol);
-</programlisting>
+ <programlisting>int socket(int domain, int type, int protocol);</programlisting>
- <para>The return value is of the same type as that of
- <function>open</function>, an integer. FreeBSD allocates
+ <para>The return value is of the same type as that of
+ <function>open</function>, an integer. FreeBSD allocates
its value from the same pool as that of file handles.
That is what allows sockets to be treated the same way as
files.</para>
<para>The <varname>domain</varname> argument tells the
system what <emphasis>protocol family</emphasis> you want
- it to use. Many of them exist, some are vendor specific,
- others are very common. They are declared in
+ it to use. Many of them exist, some are vendor specific,
+ others are very common. They are declared in
<filename>sys/socket.h</filename>.</para>
<para>Use <constant>PF_INET</constant> for
@@ -422,25 +427,24 @@ int socket(int domain, int type, int protocol);
<emphasis>unconnected</emphasis>.</para>
<para>This is on purpose: To use a telephone analogy, we
- have just attached a modem to the phone line. We have
+ have just attached a modem to the phone line. We have
neither told the modem to make a call, nor to answer if
the phone rings.</para>
</note>
</sect4>
- <sect4 xml:id="sockets-sockaddr">
+ <sect4 xml:id="sockets-sockaddr">
<title><varname>sockaddr</varname></title>
<para>Various functions of the sockets family expect the
- address of (or pointer to, to use C terminology) a small
- area of the memory. The various C declarations in the
- <filename>sys/socket.h</filename> refer to it as
- <varname>struct sockaddr</varname>. This structure is
- declared in the same file:</para>
+ address of (or pointer to, to use C terminology) a small
+ area of the memory. The various C declarations in the
+ <filename>sys/socket.h</filename> refer to it as
+ <varname>struct sockaddr</varname>. This structure is
+ declared in the same file:</para>
-<programlisting>
-/*
+ <programlisting>/*
* Structure used by kernel to store most
* addresses.
*/
@@ -449,17 +453,16 @@ struct sockaddr {
sa_family_t sa_family; /* address family */
char sa_data[14]; /* actually longer; address value */
};
-#define SOCK_MAXADDRLEN 255 /* longest possible addresses */
-</programlisting>
+#define SOCK_MAXADDRLEN 255 /* longest possible addresses */</programlisting>
- <para>Please note the <emphasis>vagueness</emphasis> with
+ <para>Please note the <emphasis>vagueness</emphasis> with
which the <varname>sa_data</varname> field is declared,
just as an array of <constant>14</constant> bytes, with
the comment hinting there can be more than
<constant>14</constant> of them.</para>
- <para>This vagueness is quite deliberate. Sockets is a very
- powerful interface. While most people perhaps think of it
+ <para>This vagueness is quite deliberate. Sockets is a very
+ powerful interface. While most people perhaps think of it
as nothing more than the Internet interface—and most
applications probably use it for that
nowadays—sockets can be used for just about
@@ -473,8 +476,7 @@ struct sockaddr {
right before the definition of
<varname>sockaddr</varname>:</para>
-<programlisting>
-/*
+ <programlisting>/*
* Address families.
*/
#define AF_UNSPEC 0 /* unspecified */
@@ -519,11 +521,9 @@ struct sockaddr {
#define AF_SCLUSTER 34 /* Sitara cluster protocol */
#define AF_ARP 35
#define AF_BLUETOOTH 36 /* Bluetooth sockets */
-#define AF_MAX 37
+#define AF_MAX 37</programlisting>
-</programlisting>
-
- <para>The one used for <acronym>IP</acronym> is
+ <para>The one used for <acronym>IP</acronym> is
<symbol>AF_INET</symbol>. It is a symbol for the constant
<constant>2</constant>.</para>
@@ -534,13 +534,12 @@ struct sockaddr {
used.</para>
<para>Specifically, whenever the <emphasis>address
- family</emphasis> is <symbol>AF_INET</symbol>, we can use
- <varname>struct sockaddr_in</varname> found in
+ family</emphasis> is <symbol>AF_INET</symbol>, we can
+ use <varname>struct sockaddr_in</varname> found in
<filename>netinet/in.h</filename>, wherever
<varname>sockaddr</varname> is expected:</para>
-<programlisting>
-/*
+ <programlisting>/*
* Socket address, internet style.
*/
struct sockaddr_in {
@@ -549,18 +548,17 @@ struct sockaddr_in {
in_port_t sin_port;
struct in_addr sin_addr;
char sin_zero[8];
-};
-</programlisting>
+};</programlisting>
- <para>We can visualize its organization this way:</para>
+ <para>We can visualize its organization this way:</para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="sockets/sain"/>
- </imageobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="sockets/sain"/>
+ </imageobject>
- <textobject>
- <literallayout class="monospaced"> 0 1 2 3
+ <textobject>
+ <literallayout class="monospaced"> 0 1 2 3
+--------+--------+-----------------+
0 | 0 | Family | Port |
+--------+--------+-----------------+
@@ -570,39 +568,41 @@ struct sockaddr_in {
+-----------------------------------+
12 | 0 |
+-----------------------------------+</literallayout>
- </textobject>
+ </textobject>
- <textobject>
- <phrase>sockaddr_in</phrase>
- </textobject>
- </mediaobject>
+ <textobject>
+ <phrase>sockaddr_in</phrase>
+ </textobject>
+ </mediaobject>
- <para>The three important fields are
+ <para>The three important fields are
<varname>sin_family</varname>, which is byte 1 of the
structure, <varname>sin_port</varname>, a 16-bit value
found in bytes 2 and 3, and <varname>sin_addr</varname>, a
32-bit integer representation of the <acronym>IP</acronym>
address, stored in bytes 4-7.</para>
- <para>Now, let us try to fill it out. Let us assume we are
+ <para>Now, let us try to fill it out. Let us assume we are
trying to write a client for the
<emphasis>daytime</emphasis> protocol, which simply states
that its server will write a text string representing the
- current date and time to port 13. We want to use
+ current date and time to port 13. We want to use
<acronym>TCP/IP</acronym>, so we need to specify
- <constant>AF_INET</constant> in the address family
- field. <constant>AF_INET</constant> is defined as
- <constant>2</constant>. Let us use the
- <acronym>IP</acronym> address of <systemitem class="ipaddress">192.43.244.18</systemitem>, which is the time
- server of US federal government (<systemitem class="fqdomainname">time.nist.gov</systemitem>).</para>
+ <constant>AF_INET</constant> in the address family field.
+ <constant>AF_INET</constant> is defined as
+ <constant>2</constant>. Let us use the
+ <acronym>IP</acronym> address of <systemitem
+ class="ipaddress">192.43.244.18</systemitem>, which is
+ the time server of US federal government (<systemitem
+ class="fqdomainname">time.nist.gov</systemitem>).</para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="sockets/sainfill"/>
- </imageobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="sockets/sainfill"/>
+ </imageobject>
- <textobject>
- <literallayout class="monospaced"> 0 1 2 3
+ <textobject>
+ <literallayout class="monospaced"> 0 1 2 3
+--------+--------+-----------------+
0 | 0 | 2 | 13 |
+-----------------+-----------------+
@@ -612,59 +612,58 @@ struct sockaddr_in {
+-----------------------------------+
12 | 0 |
+-----------------------------------+</literallayout>
- </textobject>
+ </textobject>
- <textobject>
- <phrase>Specific example of sockaddr_in</phrase>
- </textobject>
- </mediaobject>
+ <textobject>
+ <phrase>Specific example of sockaddr_in</phrase>
+ </textobject>
+ </mediaobject>
- <para>By the way the <varname>sin_addr</varname> field is
- declared as being of the <varname>struct in_addr</varname>
- type, which is defined in
- <filename>netinet/in.h</filename>:</para>
+ <para>By the way the <varname>sin_addr</varname> field is
+ declared as being of the <varname>struct in_addr</varname>
+ type, which is defined in
+ <filename>netinet/in.h</filename>:</para>
-<programlisting>
-/*
+ <programlisting>/*
* Internet address (a structure for historical reasons)
*/
struct in_addr {
in_addr_t s_addr;
-};
-</programlisting>
+};</programlisting>
- <para>In addition, <varname>in_addr_t</varname> is a 32-bit
- integer.</para>
+ <para>In addition, <varname>in_addr_t</varname> is a 32-bit
+ integer.</para>
- <para>The <systemitem class="ipaddress">192.43.244.18</systemitem> is
- just a convenient notation of expressing a 32-bit integer
- by listing all of its 8-bit bytes, starting with the
+ <para>The <systemitem
+ class="ipaddress">192.43.244.18</systemitem> is just a
+ convenient notation of expressing a 32-bit integer by
+ listing all of its 8-bit bytes, starting with the
<emphasis>most significant</emphasis> one.</para>
- <para>So far, we have viewed <varname>sockaddr</varname> as
+ <para>So far, we have viewed <varname>sockaddr</varname> as
an abstraction. Our computer does not store
<varname>short</varname> integers as a single 16-bit
- entity, but as a sequence of 2 bytes. Similarly, it stores
- 32-bit integers as a sequence of 4 bytes.</para>
+ entity, but as a sequence of 2 bytes. Similarly, it
+ stores 32-bit integers as a sequence of 4 bytes.</para>
- <para>Suppose we coded something like this:</para>
+ <para>Suppose we coded something like this:</para>
<programlisting>sa.sin_family = AF_INET;
sa.sin_port = 13;
sa.sin_addr.s_addr = (((((192 << 8) | 43) << 8) | 244) << 8) | 18;</programlisting>
- <para>What would the result look like?</para>
+ <para>What would the result look like?</para>
- <para>Well, that depends, of course. On a &pentium;, or other
- x86, based computer, it would look like this:</para>
+ <para>Well, that depends, of course. On a &pentium;, or
+ other x86, based computer, it would look like this:</para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="sockets/sainlsb"/>
- </imageobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="sockets/sainlsb"/>
+ </imageobject>
- <textobject>
- <literallayout class="monospaced"> 0 1 2 3
+ <textobject>
+ <literallayout class="monospaced"> 0 1 2 3
+--------+--------+--------+--------+
0 | 0 | 2 | 13 | 0 |
+--------+--------+--------+--------+
@@ -674,23 +673,22 @@ sa.sin_addr.s_addr = (((((192 << 8) | 43) <&l
+-----------------------------------+
12 | 0 |
+-----------------------------------+</literallayout>
- </textobject>
+ </textobject>
- <textobject>
- <phrase>sockaddr_in on an Intel system</phrase>
- </textobject>
- </mediaobject>
+ <textobject>
+ <phrase>sockaddr_in on an Intel system</phrase>
+ </textobject>
+ </mediaobject>
- <para>On a different system, it might look like this:
- </para>
+ <para>On a different system, it might look like this:</para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="sockets/sainmsb"/>
- </imageobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="sockets/sainmsb"/>
+ </imageobject>
- <textobject>
- <literallayout class="monospaced"> 0 1 2 3
+ <textobject>
+ <literallayout class="monospaced"> 0 1 2 3
+--------+--------+--------+--------+
0 | 0 | 2 | 0 | 13 |
+--------+--------+--------+--------+
@@ -700,21 +698,21 @@ sa.sin_addr.s_addr = (((((192 << 8) | 43) <&l
+-----------------------------------+
12 | 0 |
+-----------------------------------+</literallayout>
- </textobject>
+ </textobject>
- <textobject>
- <phrase>sockaddr_in on an MSB system</phrase>
- </textobject>
- </mediaobject>
+ <textobject>
+ <phrase>sockaddr_in on an MSB system</phrase>
+ </textobject>
+ </mediaobject>
- <para>And on a PDP it might look different yet. But the
+ <para>And on a PDP it might look different yet. But the
above two are the most common ways in use today.</para>
<para>Ordinarily, wanting to write portable code,
- programmers pretend that these differences do not
- exist. And they get away with it (except when they code in
- assembly language). Alas, you cannot get away with it that
- easily when coding for sockets.</para>
+ programmers pretend that these differences do not exist.
+ And they get away with it (except when they code in
+ assembly language). Alas, you cannot get away with it
+ that easily when coding for sockets.</para>
<para>Why?</para>
@@ -725,37 +723,38 @@ sa.sin_addr.s_addr = (((((192 << 8) | 43) <&l
(<acronym>LSB</acronym>) first.</para>
<para>You might be wondering, <emphasis><quote>So, will
- sockets not handle it for me?</quote></emphasis></para>
+ sockets not handle it for
+ me?</quote></emphasis></para>
<para>It will not.</para>
<para>While that answer may surprise you at first, remember
- that the general sockets interface only understands the
- <varname>sa_len</varname> and <varname>sa_family</varname>
- fields of the <varname>sockaddr</varname> structure. You
- do not have to worry about the byte order there (of
- course, on FreeBSD <varname>sa_family</varname> is only 1
- byte anyway, but many other &unix; systems do not have
- <varname>sa_len</varname> and use 2 bytes for
- <varname>sa_family</varname>, and expect the data in
- whatever order is native to the computer).</para>
+ that the general sockets interface only understands the
+ <varname>sa_len</varname> and <varname>sa_family</varname>
+ fields of the <varname>sockaddr</varname> structure. You
+ do not have to worry about the byte order there (of
+ course, on FreeBSD <varname>sa_family</varname> is only 1
+ byte anyway, but many other &unix; systems do not have
+ <varname>sa_len</varname> and use 2 bytes for
+ <varname>sa_family</varname>, and expect the data in
+ whatever order is native to the computer).</para>
<para>But the rest of the data is just
- <varname>sa_data[14]</varname> as far as sockets
- goes. Depending on the <emphasis>address
- family</emphasis>, sockets just forwards that data to its
- destination.</para>
+ <varname>sa_data[14]</varname> as far as sockets goes.
+ Depending on the <emphasis>address family</emphasis>,
+ sockets just forwards that data to its destination.</para>
<para>Indeed, when we enter a port number, it is because we
want the other computer to know what service we are asking
- for. And, when we are the server, we read the port number
+ for. And, when we are the server, we read the port number
so we know what service the other computer is expecting
- from us. Either way, sockets only has to forward the port
- number as data. It does not interpret it in any way.</para>
+ from us. Either way, sockets only has to forward the port
+ number as data. It does not interpret it in any
+ way.</para>
<para>Similarly, we enter the <acronym>IP</acronym> address
- to tell everyone on the way where to send our data
- to. Sockets, again, only forwards it as data.</para>
+ to tell everyone on the way where to send our data to.
+ Sockets, again, only forwards it as data.</para>
<para>That is why, we (the <emphasis>programmers</emphasis>,
not the <emphasis>sockets</emphasis>) have to distinguish
@@ -771,8 +770,8 @@ sa.sin_addr.s_addr = (((((192 << 8) | 43) <&l
over <acronym>IP</acronym>
<emphasis><acronym>MSB</acronym> first</emphasis>. This,
we will refer to as the <emphasis>network byte
- order</emphasis>, or simply the <emphasis>network
- order</emphasis>.</para>
+ order</emphasis>, or simply the <emphasis>network
+ order</emphasis>.</para>
<para>Now, if we compiled the above code for an Intel based
computer, our <emphasis>host byte order</emphasis> would
@@ -780,11 +779,11 @@ sa.sin_addr.s_addr = (((((192 << 8) | 43) <&l
<mediaobject>
<imageobject>
- <imagedata fileref="sockets/sainlsb"/>
- </imageobject>
+ <imagedata fileref="sockets/sainlsb"/>
+ </imageobject>
- <textobject>
- <literallayout class="monospaced"> 0 1 2 3
+ <textobject>
+ <literallayout class="monospaced"> 0 1 2 3
+--------+--------+--------+--------+
0 | 0 | 2 | 13 | 0 |
+--------+--------+--------+--------+
@@ -794,24 +793,24 @@ sa.sin_addr.s_addr = (((((192 << 8) | 43) <&l
+-----------------------------------+
12 | 0 |
+-----------------------------------+</literallayout>
- </textobject>
+ </textobject>
- <textobject>
- <phrase>Host byte order on an Intel system</phrase>
- </textobject>
- </mediaobject>
+ <textobject>
+ <phrase>Host byte order on an Intel system</phrase>
+ </textobject>
+ </mediaobject>
- <para>But the <emphasis>network byte order</emphasis>
- requires that we store the data <acronym>MSB</acronym>
- first:</para>
+ <para>But the <emphasis>network byte order</emphasis>
+ requires that we store the data <acronym>MSB</acronym>
+ first:</para>
- <mediaobject>
- <imageobject>
- <imagedata fileref="sockets/sainmsb"/>
- </imageobject>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="sockets/sainmsb"/>
+ </imageobject>
- <textobject>
- <literallayout class="monospaced"> 0 1 2 3
+ <textobject>
+ <literallayout class="monospaced"> 0 1 2 3
+--------+--------+--------+--------+
0 | 0 | 2 | 0 | 13 |
+--------+--------+--------+--------+
@@ -821,135 +820,130 @@ sa.sin_addr.s_addr = (((((192 << 8) | 43) <&l
+-----------------------------------+
12 | 0 |
+-----------------------------------+</literallayout>
- </textobject>
+ </textobject>
- <textobject>
- <phrase>Network byte order</phrase>
- </textobject>
- </mediaobject>
+ <textobject>
+ <phrase>Network byte order</phrase>
+ </textobject>
+ </mediaobject>
- <para>Unfortunately, our <emphasis>host order</emphasis> is
+ <para>Unfortunately, our <emphasis>host order</emphasis> is
the exact opposite of the <emphasis>network
- order</emphasis>.</para>
+ order</emphasis>.</para>
- <para>We have several ways of dealing with it. One would be
- to <emphasis>reverse</emphasis> the values in our code:
- </para>
+ <para>We have several ways of dealing with it. One would be
+ to <emphasis>reverse</emphasis> the values in our
+ code:</para>
<programlisting>sa.sin_family = AF_INET;
sa.sin_port = 13 << 8;
sa.sin_addr.s_addr = (((((18 << 8) | 244) << 8) | 43) << 8) | 192;</programlisting>
- <para>This will <emphasis>trick</emphasis> our compiler
- into storing the data in the <emphasis>network byte
- order</emphasis>. In some cases, this is exactly the way
- to do it (e.g., when programming in assembly
- language). In most cases, however, it can cause a
- problem.</para>
+ <para>This will <emphasis>trick</emphasis> our compiler into
+ storing the data in the <emphasis>network byte
+ order</emphasis>. In some cases, this is exactly the
+ way to do it (e.g., when programming in assembly
+ language). In most cases, however, it can cause a
+ problem.</para>
- <para>Suppose, you wrote a sockets-based program in C. You
- know it is going to run on a &pentium;, so you enter all
- your constants in reverse and force them to the
- <emphasis>network byte order</emphasis>. It works
- well.</para>
+ <para>Suppose, you wrote a sockets-based program in C. You
+ know it is going to run on a &pentium;, so you enter all
+ your constants in reverse and force them to the
+ <emphasis>network byte order</emphasis>. It works
+ well.</para>
- <para>Then, some day, your trusted old &pentium; becomes a
- rusty old &pentium;. You replace it with a system whose
- <emphasis>host order</emphasis> is the same as the
- <emphasis>network order</emphasis>. You need to recompile
- all your software. All of your software continues to
- perform well, except the one program you wrote.</para>
+ <para>Then, some day, your trusted old &pentium; becomes a
+ rusty old &pentium;. You replace it with a system whose
+ <emphasis>host order</emphasis> is the same as the
+ <emphasis>network order</emphasis>. You need to recompile
+ all your software. All of your software continues to
+ perform well, except the one program you wrote.</para>
- <para>You have since forgotten that you had forced all of
- your constants to the opposite of the <emphasis>host
- order</emphasis>. You spend some quality time tearing out
- your hair, calling the names of all gods you ever heard
- of (and some you made up), hitting your monitor with a
- nerf bat, and performing all the other traditional
- ceremonies of trying to figure out why something that has
- worked so well is suddenly not working at all.</para>
+ <para>You have since forgotten that you had forced all of
+ your constants to the opposite of the <emphasis>host
+ order</emphasis>. You spend some quality time tearing
+ out your hair, calling the names of all gods you ever
+ heard of (and some you made up), hitting your monitor with
+ a nerf bat, and performing all the other traditional
+ ceremonies of trying to figure out why something that has
+ worked so well is suddenly not working at all.</para>
- <para>Eventually, you figure it out, say a couple of swear
- words, and start rewriting your code.</para>
+ <para>Eventually, you figure it out, say a couple of swear
+ words, and start rewriting your code.</para>
- <para>Luckily, you are not the first one to face the
- problem. Someone else has created the &man.htons.3; and
- &man.htonl.3; C functions to convert a
- <varname>short</varname> and <varname>long</varname>
- respectively from the <emphasis>host byte
- order</emphasis> to the <emphasis>network byte
- order</emphasis>, and the &man.ntohs.3; and &man.ntohl.3;
- C functions to go the other way.</para>
+ <para>Luckily, you are not the first one to face the
+ problem. Someone else has created the &man.htons.3; and
+ &man.htonl.3; C functions to convert a
+ <varname>short</varname> and <varname>long</varname>
+ respectively from the <emphasis>host byte order</emphasis>
+ to the <emphasis>network byte order</emphasis>, and the
+ &man.ntohs.3; and &man.ntohl.3; C functions to go the
+ other way.</para>
- <para>On <emphasis><acronym>MSB</acronym>-first</emphasis>
- systems these functions do nothing. On
- <emphasis><acronym>LSB</acronym>-first</emphasis> systems
- they convert values to the proper order.</para>
+ <para>On <emphasis><acronym>MSB</acronym>-first</emphasis>
+ systems these functions do nothing. On
+ <emphasis><acronym>LSB</acronym>-first</emphasis> systems
+ they convert values to the proper order.</para>
- <para>So, regardless of what system your software is
- compiled on, your data will end up in the correct order
- if you use these functions.</para>
-
- </sect4>
-
+ <para>So, regardless of what system your software is
+ compiled on, your data will end up in the correct order if
+ you use these functions.</para>
+ </sect4>
</sect3>
<sect3 xml:id="sockets-client-functions">
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-all
mailing list