1775 lines
216 KiB
HTML
1775 lines
216 KiB
HTML
|
<!DOCTYPE html>
|
|||
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="utf-8" />
|
|||
|
|
<meta name="generator" content="pandoc" />
|
|||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
|
|||
|
|
<title>Beej's Guide to Network Programming</title>
|
|||
|
|
<style>
|
|||
|
|
html {
|
|||
|
|
color: #1a1a1a;
|
|||
|
|
background-color: #fdfdfd;
|
|||
|
|
}
|
|||
|
|
body {
|
|||
|
|
margin: 0 auto;
|
|||
|
|
max-width: 36em;
|
|||
|
|
padding-left: 50px;
|
|||
|
|
padding-right: 50px;
|
|||
|
|
padding-top: 50px;
|
|||
|
|
padding-bottom: 50px;
|
|||
|
|
hyphens: auto;
|
|||
|
|
overflow-wrap: break-word;
|
|||
|
|
text-rendering: optimizeLegibility;
|
|||
|
|
font-kerning: normal;
|
|||
|
|
}
|
|||
|
|
@media (max-width: 600px) {
|
|||
|
|
body {
|
|||
|
|
font-size: 0.9em;
|
|||
|
|
padding: 12px;
|
|||
|
|
}
|
|||
|
|
h1 {
|
|||
|
|
font-size: 1.8em;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
@media print {
|
|||
|
|
html {
|
|||
|
|
background-color: white;
|
|||
|
|
}
|
|||
|
|
body {
|
|||
|
|
background-color: transparent;
|
|||
|
|
color: black;
|
|||
|
|
font-size: 12pt;
|
|||
|
|
}
|
|||
|
|
p, h2, h3 {
|
|||
|
|
orphans: 3;
|
|||
|
|
widows: 3;
|
|||
|
|
}
|
|||
|
|
h2, h3, h4 {
|
|||
|
|
page-break-after: avoid;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
p {
|
|||
|
|
margin: 1em 0;
|
|||
|
|
}
|
|||
|
|
a {
|
|||
|
|
color: #1a1a1a;
|
|||
|
|
}
|
|||
|
|
a:visited {
|
|||
|
|
color: #1a1a1a;
|
|||
|
|
}
|
|||
|
|
img {
|
|||
|
|
max-width: 100%;
|
|||
|
|
}
|
|||
|
|
h1, h2, h3, h4, h5, h6 {
|
|||
|
|
margin-top: 1.4em;
|
|||
|
|
}
|
|||
|
|
h5, h6 {
|
|||
|
|
font-size: 1em;
|
|||
|
|
font-style: italic;
|
|||
|
|
}
|
|||
|
|
h6 {
|
|||
|
|
font-weight: normal;
|
|||
|
|
}
|
|||
|
|
ol, ul {
|
|||
|
|
padding-left: 1.7em;
|
|||
|
|
margin-top: 1em;
|
|||
|
|
}
|
|||
|
|
li > ol, li > ul {
|
|||
|
|
margin-top: 0;
|
|||
|
|
}
|
|||
|
|
blockquote {
|
|||
|
|
margin: 1em 0 1em 1.7em;
|
|||
|
|
padding-left: 1em;
|
|||
|
|
border-left: 2px solid #e6e6e6;
|
|||
|
|
color: #606060;
|
|||
|
|
}
|
|||
|
|
code {
|
|||
|
|
font-family: Menlo, Monaco, Consolas, 'Lucida Console', monospace;
|
|||
|
|
font-size: 85%;
|
|||
|
|
margin: 0;
|
|||
|
|
hyphens: manual;
|
|||
|
|
}
|
|||
|
|
pre {
|
|||
|
|
margin: 1em 0;
|
|||
|
|
overflow: auto;
|
|||
|
|
}
|
|||
|
|
pre code {
|
|||
|
|
padding: 0;
|
|||
|
|
overflow: visible;
|
|||
|
|
overflow-wrap: normal;
|
|||
|
|
}
|
|||
|
|
.sourceCode {
|
|||
|
|
background-color: transparent;
|
|||
|
|
overflow: visible;
|
|||
|
|
}
|
|||
|
|
hr {
|
|||
|
|
background-color: #1a1a1a;
|
|||
|
|
border: none;
|
|||
|
|
height: 1px;
|
|||
|
|
margin: 1em 0;
|
|||
|
|
}
|
|||
|
|
table {
|
|||
|
|
margin: 1em 0;
|
|||
|
|
border-collapse: collapse;
|
|||
|
|
width: 100%;
|
|||
|
|
overflow-x: auto;
|
|||
|
|
display: block;
|
|||
|
|
font-variant-numeric: lining-nums tabular-nums;
|
|||
|
|
}
|
|||
|
|
table caption {
|
|||
|
|
margin-bottom: 0.75em;
|
|||
|
|
}
|
|||
|
|
tbody {
|
|||
|
|
margin-top: 0.5em;
|
|||
|
|
border-top: 1px solid #1a1a1a;
|
|||
|
|
border-bottom: 1px solid #1a1a1a;
|
|||
|
|
}
|
|||
|
|
th {
|
|||
|
|
border-top: 1px solid #1a1a1a;
|
|||
|
|
padding: 0.25em 0.5em 0.25em 0.5em;
|
|||
|
|
}
|
|||
|
|
td {
|
|||
|
|
padding: 0.125em 0.5em 0.25em 0.5em;
|
|||
|
|
}
|
|||
|
|
header {
|
|||
|
|
margin-bottom: 4em;
|
|||
|
|
text-align: center;
|
|||
|
|
}
|
|||
|
|
#TOC li {
|
|||
|
|
list-style: none;
|
|||
|
|
}
|
|||
|
|
#TOC ul {
|
|||
|
|
padding-left: 1.3em;
|
|||
|
|
}
|
|||
|
|
#TOC > ul {
|
|||
|
|
padding-left: 0;
|
|||
|
|
}
|
|||
|
|
#TOC a:not(:hover) {
|
|||
|
|
text-decoration: none;
|
|||
|
|
}
|
|||
|
|
code{white-space: pre-wrap;}
|
|||
|
|
span.smallcaps{font-variant: small-caps;}
|
|||
|
|
div.columns{display: flex; gap: min(4vw, 1.5em);}
|
|||
|
|
div.column{flex: auto; overflow-x: auto;}
|
|||
|
|
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
|
|||
|
|
ul.task-list{list-style: none;}
|
|||
|
|
ul.task-list li input[type="checkbox"] {
|
|||
|
|
width: 0.8em;
|
|||
|
|
margin: 0 0.8em 0.2em -1.6em;
|
|||
|
|
vertical-align: middle;
|
|||
|
|
}
|
|||
|
|
/* CSS for syntax highlighting */
|
|||
|
|
pre > code.sourceCode { white-space: pre; position: relative; }
|
|||
|
|
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
|
|||
|
|
pre > code.sourceCode > span:empty { height: 1.2em; }
|
|||
|
|
.sourceCode { overflow: visible; }
|
|||
|
|
code.sourceCode > span { color: inherit; text-decoration: inherit; }
|
|||
|
|
div.sourceCode { margin: 1em 0; }
|
|||
|
|
pre.sourceCode { margin: 0; }
|
|||
|
|
@media screen {
|
|||
|
|
div.sourceCode { overflow: auto; }
|
|||
|
|
}
|
|||
|
|
@media print {
|
|||
|
|
pre > code.sourceCode { white-space: pre-wrap; }
|
|||
|
|
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
|
|||
|
|
}
|
|||
|
|
pre.numberSource code
|
|||
|
|
{ counter-reset: source-line 0; }
|
|||
|
|
pre.numberSource code > span
|
|||
|
|
{ position: relative; left: -4em; counter-increment: source-line; }
|
|||
|
|
pre.numberSource code > span > a:first-child::before
|
|||
|
|
{ content: counter(source-line);
|
|||
|
|
position: relative; left: -1em; text-align: right; vertical-align: baseline;
|
|||
|
|
border: none; display: inline-block;
|
|||
|
|
-webkit-touch-callout: none; -webkit-user-select: none;
|
|||
|
|
-khtml-user-select: none; -moz-user-select: none;
|
|||
|
|
-ms-user-select: none; user-select: none;
|
|||
|
|
padding: 0 4px; width: 4em;
|
|||
|
|
color: #aaaaaa;
|
|||
|
|
}
|
|||
|
|
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
|
|||
|
|
div.sourceCode
|
|||
|
|
{ }
|
|||
|
|
@media screen {
|
|||
|
|
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
|
|||
|
|
}
|
|||
|
|
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
|
|||
|
|
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
|
|||
|
|
code span.at { color: #7d9029; } /* Attribute */
|
|||
|
|
code span.bn { color: #40a070; } /* BaseN */
|
|||
|
|
code span.bu { color: #008000; } /* BuiltIn */
|
|||
|
|
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
|
|||
|
|
code span.ch { color: #4070a0; } /* Char */
|
|||
|
|
code span.cn { color: #880000; } /* Constant */
|
|||
|
|
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
|
|||
|
|
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
|
|||
|
|
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
|
|||
|
|
code span.dt { color: #902000; } /* DataType */
|
|||
|
|
code span.dv { color: #40a070; } /* DecVal */
|
|||
|
|
code span.er { color: #ff0000; font-weight: bold; } /* Error */
|
|||
|
|
code span.ex { } /* Extension */
|
|||
|
|
code span.fl { color: #40a070; } /* Float */
|
|||
|
|
code span.fu { color: #06287e; } /* Function */
|
|||
|
|
code span.im { color: #008000; font-weight: bold; } /* Import */
|
|||
|
|
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
|
|||
|
|
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
|
|||
|
|
code span.op { color: #666666; } /* Operator */
|
|||
|
|
code span.ot { color: #007020; } /* Other */
|
|||
|
|
code span.pp { color: #bc7a00; } /* Preprocessor */
|
|||
|
|
code span.sc { color: #4070a0; } /* SpecialChar */
|
|||
|
|
code span.ss { color: #bb6688; } /* SpecialString */
|
|||
|
|
code span.st { color: #4070a0; } /* String */
|
|||
|
|
code span.va { color: #19177c; } /* Variable */
|
|||
|
|
code span.vs { color: #4070a0; } /* VerbatimString */
|
|||
|
|
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
|
|||
|
|
</style>
|
|||
|
|
<link href="https://fonts.googleapis.com/css?family=Roboto|Roboto+Mono&display=swap" rel="stylesheet">
|
|||
|
|
|
|||
|
|
<!-- BG custom styling -->
|
|||
|
|
<style type="text/css">
|
|||
|
|
/* Fix for line numbers not visible */
|
|||
|
|
pre.numberSource code > span {
|
|||
|
|
left: -1em;
|
|||
|
|
}
|
|||
|
|
pre.numberSource {
|
|||
|
|
margin-left: initial;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/* Put some space after the section numbers */
|
|||
|
|
span.toc-section-number::after {
|
|||
|
|
content: "\a0\a0\a0"; /* non-breaking whitespace */
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/* Hide underlines on code number links */
|
|||
|
|
pre > code.sourceCode > span > a:first-child::before {
|
|||
|
|
text-decoration: none;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/* Color the source blocks */
|
|||
|
|
div.sourceCode {
|
|||
|
|
background-color: #f0f0f0;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/* Fix iOS big text rendering issue */
|
|||
|
|
pre > code.sourceCode > span {
|
|||
|
|
display: initial;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
|
|||
|
|
/* Color the inline code */
|
|||
|
|
code:not(.sourceCode) {
|
|||
|
|
background: #f0f0f0;
|
|||
|
|
padding-left: 0.2em;
|
|||
|
|
padding-right: 0.2em;
|
|||
|
|
border-radius: 0.2em;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/* Keep code tags from wrapping in tables */
|
|||
|
|
tbody code {
|
|||
|
|
white-space: nowrap;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
td {
|
|||
|
|
vertical-align: top;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
body {
|
|||
|
|
font-size: 12pt;
|
|||
|
|
max-width: 43em;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
figure {
|
|||
|
|
text-align: center;
|
|||
|
|
}
|
|||
|
|
</style>
|
|||
|
|
<!--[if lt IE 9]>
|
|||
|
|
<script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
|
|||
|
|
<![endif]-->
|
|||
|
|
</head>
|
|||
|
|
<body>
|
|||
|
|
<div style="text-align:center"><span><a href="common-questions.html">Prev</a> | </span><a href="index.html">Contents</a><span> | <a href="more-references.html">Next</a></span></div><hr>
|
|||
|
|
<h1 data-number="9" id="man-pages"><span class="header-section-number">9</span> Man Pages</h1>
|
|||
|
|
<p></p>
|
|||
|
|
<p>In the Unix world, there are a lot of manuals. They have little sections that describe individual functions that you have at your disposal.</p>
|
|||
|
|
<p>Of course, <code>manual</code> would be too much of a thing to type. I mean, no one in the Unix world, including myself, likes to type that much. Indeed I could go on and on at great length about how much I prefer to be terse but instead I shall be brief and not bore you with long-winded diatribes about how utterly amazingly brief I prefer to be in virtually all circumstances in their entirety.</p>
|
|||
|
|
<p><em>[Applause]</em></p>
|
|||
|
|
<p>Thank you. What I am getting at is that these pages are called “man pages” in the Unix world, and I have included my own personal truncated variant here for your reading enjoyment. The thing is, many of these functions are way more general purpose than I’m letting on, but I’m only going to present the parts that are relevant for Internet Sockets Programming.</p>
|
|||
|
|
<p>But wait! That’s not all that’s wrong with my man pages:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>They are incomplete and only show the basics from the guide.</li>
|
|||
|
|
<li>There are many more man pages than this in the real world.</li>
|
|||
|
|
<li>They are different than the ones on your system.</li>
|
|||
|
|
<li>The header files might be different for certain functions on your system.</li>
|
|||
|
|
<li>The function parameters might be different for certain functions on your system.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>If you want the real information, check your local Unix man pages by typing <code>man whatever</code>, where “whatever” is something that you’re incredibly interested in, such as “<code>accept</code>”. (I’m sure Microsoft Visual Studio has something similar in their help section. But “man” is better because it is one byte more concise than “help”. Unix wins again!)</p>
|
|||
|
|
<p>So, if these are so flawed, why even include them at all in the Guide? Well, there are a few reasons, but the best are that (a) these versions are geared specifically toward network programming and are easier to digest than the real ones, and (b) these versions contain examples!</p>
|
|||
|
|
<p>Oh! And speaking of the examples, I don’t tend to put in all the error checking because it really increases the length of the code. But you should absolutely do error checking pretty much any time you make any of the system calls unless you’re totally 100% sure it’s not going to fail, and you should probably do it even then!</p>
|
|||
|
|
<p></p>
|
|||
|
|
<h2 data-number="9.1" id="acceptman"><span class="header-section-number">9.1</span> <code>accept()</code></h2>
|
|||
|
|
<p></p>
|
|||
|
|
<p>Accept an incoming connection on a listening socket</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb81"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb81-1"><a href="man-pages.html#cb81-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/types.h></span></span>
|
|||
|
|
<span id="cb81-2"><a href="man-pages.html#cb81-2" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb81-3"><a href="man-pages.html#cb81-3" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb81-4"><a href="man-pages.html#cb81-4" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> accept<span class="op">(</span><span class="dt">int</span> s<span class="op">,</span> <span class="kw">struct</span> sockaddr <span class="op">*</span>addr<span class="op">,</span> socklen_t <span class="op">*</span>addrlen<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description">Description</h3>
|
|||
|
|
<p>Once you’ve gone through the trouble of getting a <code>SOCK_STREAM</code> socket and setting it up for incoming connections with <code>listen()</code>, then you call <code>accept()</code> to actually get yourself a new socket descriptor to use for subsequent communication with the newly connected client.</p>
|
|||
|
|
<p>The old socket that you are using for listening is still there, and will be used for further <code>accept()</code> calls as they come in.</p>
|
|||
|
|
<table>
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 14%" />
|
|||
|
|
<col style="width: 85%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="header">
|
|||
|
|
<th>Parameter</th>
|
|||
|
|
<th>Description</th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>s</code></td>
|
|||
|
|
<td>The <code>listen()</code>ing socket descriptor.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>addr</code></td>
|
|||
|
|
<td>This is filled in with the address of the site that’s connecting to you.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>addrlen</code></td>
|
|||
|
|
<td>This is filled in with the <code>sizeof()</code> the structure returned in the <code>addr</code> parameter. You can safely ignore it if you assume you’re getting a <code>struct sockaddr_in</code> back, which you know you are, because that’s the type you passed in for <code>addr</code>.</td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
<p><code>accept()</code> will normally block, and you can use <code>select()</code> to peek on the listening socket descriptor ahead of time to see if it’s “ready to read”. If so, then there’s a new connection waiting to be <code>accept()</code>ed! Yay! Alternatively, you could set the <code>O_NONBLOCK</code> flag on the listening socket using <code>fcntl()</code>, and then it will never block, choosing instead to return <code>-1</code> with <code>errno</code> set to <code>EWOULDBLOCK</code>.</p>
|
|||
|
|
<p>The socket descriptor returned by <code>accept()</code> is a bona fide socket descriptor, open and connected to the remote host. You have to <code>close()</code> it when you’re done with it.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value">Return Value</h3>
|
|||
|
|
<p><code>accept()</code> returns the newly connected socket descriptor, or <code>-1</code> on error, with <code>errno</code> set appropriately.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb82"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb82-1"><a href="man-pages.html#cb82-1"></a><span class="kw">struct</span> sockaddr_storage their_addr<span class="op">;</span></span>
|
|||
|
|
<span id="cb82-2"><a href="man-pages.html#cb82-2"></a>socklen_t addr_size<span class="op">;</span></span>
|
|||
|
|
<span id="cb82-3"><a href="man-pages.html#cb82-3"></a><span class="kw">struct</span> addrinfo hints<span class="op">,</span> <span class="op">*</span>res<span class="op">;</span></span>
|
|||
|
|
<span id="cb82-4"><a href="man-pages.html#cb82-4"></a><span class="dt">int</span> sockfd<span class="op">,</span> new_fd<span class="op">;</span></span>
|
|||
|
|
<span id="cb82-5"><a href="man-pages.html#cb82-5"></a></span>
|
|||
|
|
<span id="cb82-6"><a href="man-pages.html#cb82-6"></a><span class="co">// first, load up address structs with getaddrinfo():</span></span>
|
|||
|
|
<span id="cb82-7"><a href="man-pages.html#cb82-7"></a></span>
|
|||
|
|
<span id="cb82-8"><a href="man-pages.html#cb82-8"></a>memset<span class="op">(&</span>hints<span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="kw">sizeof</span> hints<span class="op">);</span></span>
|
|||
|
|
<span id="cb82-9"><a href="man-pages.html#cb82-9"></a>hints<span class="op">.</span>ai_family <span class="op">=</span> AF_UNSPEC<span class="op">;</span> <span class="co">// use IPv4 or IPv6, whichever</span></span>
|
|||
|
|
<span id="cb82-10"><a href="man-pages.html#cb82-10"></a>hints<span class="op">.</span>ai_socktype <span class="op">=</span> SOCK_STREAM<span class="op">;</span></span>
|
|||
|
|
<span id="cb82-11"><a href="man-pages.html#cb82-11"></a>hints<span class="op">.</span>ai_flags <span class="op">=</span> AI_PASSIVE<span class="op">;</span> <span class="co">// fill in my IP for me</span></span>
|
|||
|
|
<span id="cb82-12"><a href="man-pages.html#cb82-12"></a></span>
|
|||
|
|
<span id="cb82-13"><a href="man-pages.html#cb82-13"></a>getaddrinfo<span class="op">(</span>NULL<span class="op">,</span> MYPORT<span class="op">,</span> <span class="op">&</span>hints<span class="op">,</span> <span class="op">&</span>res<span class="op">);</span></span>
|
|||
|
|
<span id="cb82-14"><a href="man-pages.html#cb82-14"></a></span>
|
|||
|
|
<span id="cb82-15"><a href="man-pages.html#cb82-15"></a><span class="co">// make a socket, bind it, and listen on it:</span></span>
|
|||
|
|
<span id="cb82-16"><a href="man-pages.html#cb82-16"></a></span>
|
|||
|
|
<span id="cb82-17"><a href="man-pages.html#cb82-17"></a>sockfd <span class="op">=</span> socket<span class="op">(</span>res<span class="op">-></span>ai_family<span class="op">,</span> res<span class="op">-></span>ai_socktype<span class="op">,</span> res<span class="op">-></span>ai_protocol<span class="op">);</span></span>
|
|||
|
|
<span id="cb82-18"><a href="man-pages.html#cb82-18"></a>bind<span class="op">(</span>sockfd<span class="op">,</span> res<span class="op">-></span>ai_addr<span class="op">,</span> res<span class="op">-></span>ai_addrlen<span class="op">);</span></span>
|
|||
|
|
<span id="cb82-19"><a href="man-pages.html#cb82-19"></a>listen<span class="op">(</span>sockfd<span class="op">,</span> BACKLOG<span class="op">);</span></span>
|
|||
|
|
<span id="cb82-20"><a href="man-pages.html#cb82-20"></a></span>
|
|||
|
|
<span id="cb82-21"><a href="man-pages.html#cb82-21"></a><span class="co">// now accept an incoming connection:</span></span>
|
|||
|
|
<span id="cb82-22"><a href="man-pages.html#cb82-22"></a></span>
|
|||
|
|
<span id="cb82-23"><a href="man-pages.html#cb82-23"></a>addr_size <span class="op">=</span> <span class="kw">sizeof</span> their_addr<span class="op">;</span></span>
|
|||
|
|
<span id="cb82-24"><a href="man-pages.html#cb82-24"></a>new_fd <span class="op">=</span> accept<span class="op">(</span>sockfd<span class="op">,</span> <span class="op">(</span><span class="kw">struct</span> sockaddr <span class="op">*)&</span>their_addr<span class="op">,</span> <span class="op">&</span>addr_size<span class="op">);</span></span>
|
|||
|
|
<span id="cb82-25"><a href="man-pages.html#cb82-25"></a></span>
|
|||
|
|
<span id="cb82-26"><a href="man-pages.html#cb82-26"></a><span class="co">// ready to communicate on socket descriptor new_fd!</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#socketman"><code>socket()</code></a>, <a href="man-pages.html#getaddrinfoman"><code>getaddrinfo()</code></a>, <a href="man-pages.html#listenman"><code>listen()</code></a>, <a href="man-pages.html#structsockaddrman"><code>struct sockaddr_in</code></a></p>
|
|||
|
|
<h2 data-number="9.2" id="bindman"><span class="header-section-number">9.2</span> <code>bind()</code></h2>
|
|||
|
|
<p></p>
|
|||
|
|
<p>Associate a socket with an IP address and port number</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-1">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb83"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb83-1"><a href="man-pages.html#cb83-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/types.h></span></span>
|
|||
|
|
<span id="cb83-2"><a href="man-pages.html#cb83-2" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb83-3"><a href="man-pages.html#cb83-3" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb83-4"><a href="man-pages.html#cb83-4" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> bind<span class="op">(</span><span class="dt">int</span> sockfd<span class="op">,</span> <span class="kw">struct</span> sockaddr <span class="op">*</span>my_addr<span class="op">,</span> socklen_t addrlen<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-1">Description</h3>
|
|||
|
|
<p>When a remote machine wants to connect to your server program, it needs two pieces of information: the IP address and the port number. The <code>bind()</code> call allows you to do just that.</p>
|
|||
|
|
<p>First, you call <code>getaddrinfo()</code> to load up a <code>struct sockaddr</code> with the destination address and port information. Then you call <code>socket()</code> to get a socket descriptor, and then you pass the socket and address into <code>bind()</code>, and the IP address and port are magically (using actual magic) bound to the socket!</p>
|
|||
|
|
<p>If you don’t know your IP address, or you know you only have one IP address on the machine, or you don’t care which of the machine’s IP addresses is used, you can simply pass the <code>AI_PASSIVE</code> flag in the <code>hints</code> parameter to <code>getaddrinfo()</code>. What this does is fill in the IP address part of the <code>struct sockaddr</code> with a special value that tells <code>bind()</code> that it should automatically fill in this host’s IP address.</p>
|
|||
|
|
<p>What what? What special value is loaded into the <code>struct sockaddr</code>’s IP address to cause it to auto-fill the address with the current host? I’ll tell you, but keep in mind this is only if you’re filling out the <code>struct sockaddr</code> by hand; if not, use the results from <code>getaddrinfo()</code>, as per above. In IPv4, the <code>sin_addr.s_addr</code> field of the <code>struct sockaddr_in</code> structure is set to <code>INADDR_ANY</code>. In IPv6, the <code>sin6_addr</code> field of the <code>struct sockaddr_in6</code> structure is assigned into from the global variable <code>in6addr_any</code>. Or, if you’re declaring a new <code>struct in6_addr</code>, you can initialize it to <code>IN6ADDR_ANY_INIT</code>.</p>
|
|||
|
|
<p>Lastly, the <code>addrlen</code> parameter should be set to <code>sizeof my_addr</code>.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-1">Return Value</h3>
|
|||
|
|
<p>Returns zero on success, or <code>-1</code> on error (and <code>errno</code> will be set accordingly).</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-1">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb84"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb84-1"><a href="man-pages.html#cb84-1"></a><span class="co">// modern way of doing things with getaddrinfo()</span></span>
|
|||
|
|
<span id="cb84-2"><a href="man-pages.html#cb84-2"></a></span>
|
|||
|
|
<span id="cb84-3"><a href="man-pages.html#cb84-3"></a><span class="kw">struct</span> addrinfo hints<span class="op">,</span> <span class="op">*</span>res<span class="op">;</span></span>
|
|||
|
|
<span id="cb84-4"><a href="man-pages.html#cb84-4"></a><span class="dt">int</span> sockfd<span class="op">;</span></span>
|
|||
|
|
<span id="cb84-5"><a href="man-pages.html#cb84-5"></a></span>
|
|||
|
|
<span id="cb84-6"><a href="man-pages.html#cb84-6"></a><span class="co">// first, load up address structs with getaddrinfo():</span></span>
|
|||
|
|
<span id="cb84-7"><a href="man-pages.html#cb84-7"></a></span>
|
|||
|
|
<span id="cb84-8"><a href="man-pages.html#cb84-8"></a>memset<span class="op">(&</span>hints<span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="kw">sizeof</span> hints<span class="op">);</span></span>
|
|||
|
|
<span id="cb84-9"><a href="man-pages.html#cb84-9"></a>hints<span class="op">.</span>ai_family <span class="op">=</span> AF_UNSPEC<span class="op">;</span> <span class="co">// use IPv4 or IPv6, whichever</span></span>
|
|||
|
|
<span id="cb84-10"><a href="man-pages.html#cb84-10"></a>hints<span class="op">.</span>ai_socktype <span class="op">=</span> SOCK_STREAM<span class="op">;</span></span>
|
|||
|
|
<span id="cb84-11"><a href="man-pages.html#cb84-11"></a>hints<span class="op">.</span>ai_flags <span class="op">=</span> AI_PASSIVE<span class="op">;</span> <span class="co">// fill in my IP for me</span></span>
|
|||
|
|
<span id="cb84-12"><a href="man-pages.html#cb84-12"></a></span>
|
|||
|
|
<span id="cb84-13"><a href="man-pages.html#cb84-13"></a>getaddrinfo<span class="op">(</span>NULL<span class="op">,</span> <span class="st">"3490"</span><span class="op">,</span> <span class="op">&</span>hints<span class="op">,</span> <span class="op">&</span>res<span class="op">);</span></span>
|
|||
|
|
<span id="cb84-14"><a href="man-pages.html#cb84-14"></a></span>
|
|||
|
|
<span id="cb84-15"><a href="man-pages.html#cb84-15"></a><span class="co">// make a socket:</span></span>
|
|||
|
|
<span id="cb84-16"><a href="man-pages.html#cb84-16"></a><span class="co">// (you should actually walk the "res" linked list and error-check!)</span></span>
|
|||
|
|
<span id="cb84-17"><a href="man-pages.html#cb84-17"></a></span>
|
|||
|
|
<span id="cb84-18"><a href="man-pages.html#cb84-18"></a>sockfd <span class="op">=</span> socket<span class="op">(</span>res<span class="op">-></span>ai_family<span class="op">,</span> res<span class="op">-></span>ai_socktype<span class="op">,</span> res<span class="op">-></span>ai_protocol<span class="op">);</span></span>
|
|||
|
|
<span id="cb84-19"><a href="man-pages.html#cb84-19"></a></span>
|
|||
|
|
<span id="cb84-20"><a href="man-pages.html#cb84-20"></a><span class="co">// bind it to the port we passed in to getaddrinfo():</span></span>
|
|||
|
|
<span id="cb84-21"><a href="man-pages.html#cb84-21"></a></span>
|
|||
|
|
<span id="cb84-22"><a href="man-pages.html#cb84-22"></a>bind<span class="op">(</span>sockfd<span class="op">,</span> res<span class="op">-></span>ai_addr<span class="op">,</span> res<span class="op">-></span>ai_addrlen<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<div class="sourceCode" id="cb85"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb85-1"><a href="man-pages.html#cb85-1"></a><span class="co">// example of packing a struct by hand, IPv4</span></span>
|
|||
|
|
<span id="cb85-2"><a href="man-pages.html#cb85-2"></a></span>
|
|||
|
|
<span id="cb85-3"><a href="man-pages.html#cb85-3"></a><span class="kw">struct</span> sockaddr_in myaddr<span class="op">;</span></span>
|
|||
|
|
<span id="cb85-4"><a href="man-pages.html#cb85-4"></a><span class="dt">int</span> s<span class="op">;</span></span>
|
|||
|
|
<span id="cb85-5"><a href="man-pages.html#cb85-5"></a></span>
|
|||
|
|
<span id="cb85-6"><a href="man-pages.html#cb85-6"></a>myaddr<span class="op">.</span>sin_family <span class="op">=</span> AF_INET<span class="op">;</span></span>
|
|||
|
|
<span id="cb85-7"><a href="man-pages.html#cb85-7"></a>myaddr<span class="op">.</span>sin_port <span class="op">=</span> htons<span class="op">(</span><span class="dv">3490</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb85-8"><a href="man-pages.html#cb85-8"></a></span>
|
|||
|
|
<span id="cb85-9"><a href="man-pages.html#cb85-9"></a><span class="co">// you can specify an IP address:</span></span>
|
|||
|
|
<span id="cb85-10"><a href="man-pages.html#cb85-10"></a>inet_pton<span class="op">(</span>AF_INET<span class="op">,</span> <span class="st">"63.161.169.137"</span><span class="op">,</span> <span class="op">&(</span>myaddr<span class="op">.</span>sin_addr<span class="op">));</span></span>
|
|||
|
|
<span id="cb85-11"><a href="man-pages.html#cb85-11"></a></span>
|
|||
|
|
<span id="cb85-12"><a href="man-pages.html#cb85-12"></a><span class="co">// or you can let it automatically select one:</span></span>
|
|||
|
|
<span id="cb85-13"><a href="man-pages.html#cb85-13"></a>myaddr<span class="op">.</span>sin_addr<span class="op">.</span>s_addr <span class="op">=</span> INADDR_ANY<span class="op">;</span></span>
|
|||
|
|
<span id="cb85-14"><a href="man-pages.html#cb85-14"></a></span>
|
|||
|
|
<span id="cb85-15"><a href="man-pages.html#cb85-15"></a>s <span class="op">=</span> socket<span class="op">(</span>PF_INET<span class="op">,</span> SOCK_STREAM<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb85-16"><a href="man-pages.html#cb85-16"></a>bind<span class="op">(</span>s<span class="op">,</span> <span class="op">(</span><span class="kw">struct</span> sockaddr<span class="op">*)&</span>myaddr<span class="op">,</span> <span class="kw">sizeof</span> myaddr<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-1">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#getaddrinfoman"><code>getaddrinfo()</code></a>, <a href="man-pages.html#socketman"><code>socket()</code></a>, <a href="man-pages.html#structsockaddrman"><code>struct sockaddr_in</code></a>, <a href="man-pages.html#structsockaddrman"><code>struct in_addr</code></a></p>
|
|||
|
|
<h2 data-number="9.3" id="connectman"><span class="header-section-number">9.3</span> <code>connect()</code></h2>
|
|||
|
|
<p></p>
|
|||
|
|
<p>Connect a socket to a server</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-2">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb86"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb86-1"><a href="man-pages.html#cb86-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/types.h></span></span>
|
|||
|
|
<span id="cb86-2"><a href="man-pages.html#cb86-2" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb86-3"><a href="man-pages.html#cb86-3" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb86-4"><a href="man-pages.html#cb86-4" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> connect<span class="op">(</span><span class="dt">int</span> sockfd<span class="op">,</span> <span class="dt">const</span> <span class="kw">struct</span> sockaddr <span class="op">*</span>serv_addr<span class="op">,</span></span>
|
|||
|
|
<span id="cb86-5"><a href="man-pages.html#cb86-5" aria-hidden="true" tabindex="-1"></a> socklen_t addrlen<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-2">Description</h3>
|
|||
|
|
<p>Once you’ve built a socket descriptor with the <code>socket()</code> call, you can <code>connect()</code> that socket to a remote server using the well-named <code>connect()</code> system call. All you need to do is pass it the socket descriptor and the address of the server you’re interested in getting to know better. (Oh, and the length of the address, which is commonly passed to functions like this.)</p>
|
|||
|
|
<p>Usually this information comes along as the result of a call to <code>getaddrinfo()</code>, but you can fill out your own <code>struct sockaddr</code> if you want to.</p>
|
|||
|
|
<p>If you haven’t yet called <code>bind()</code> on the socket descriptor, it is automatically bound to your IP address and a random local port. This is usually just fine with you if you’re not a server, since you really don’t care what your local port is; you only care what the remote port is so you can put it in the <code>serv_addr</code> parameter. You <em>can</em> call <code>bind()</code> if you really want your client socket to be on a specific IP address and port, but this is pretty rare.</p>
|
|||
|
|
<p>Once the socket is <code>connect()</code>ed, you’re free to <code>send()</code> and <code>recv()</code> data on it to your heart’s content.</p>
|
|||
|
|
<p> Special note: if you <code>connect()</code> a <code>SOCK_DGRAM</code> UDP socket to a remote host, you can use <code>send()</code> and <code>recv()</code> as well as <code>sendto()</code> and <code>recvfrom()</code>. If you want.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-2">Return Value</h3>
|
|||
|
|
<p>Returns zero on success, or <code>-1</code> on error (and <code>errno</code> will be set accordingly).</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-2">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb87"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb87-1"><a href="man-pages.html#cb87-1"></a><span class="co">// connect to www.example.com port 80 (http)</span></span>
|
|||
|
|
<span id="cb87-2"><a href="man-pages.html#cb87-2"></a></span>
|
|||
|
|
<span id="cb87-3"><a href="man-pages.html#cb87-3"></a><span class="kw">struct</span> addrinfo hints<span class="op">,</span> <span class="op">*</span>res<span class="op">;</span></span>
|
|||
|
|
<span id="cb87-4"><a href="man-pages.html#cb87-4"></a><span class="dt">int</span> sockfd<span class="op">;</span></span>
|
|||
|
|
<span id="cb87-5"><a href="man-pages.html#cb87-5"></a></span>
|
|||
|
|
<span id="cb87-6"><a href="man-pages.html#cb87-6"></a><span class="co">// first, load up address structs with getaddrinfo():</span></span>
|
|||
|
|
<span id="cb87-7"><a href="man-pages.html#cb87-7"></a></span>
|
|||
|
|
<span id="cb87-8"><a href="man-pages.html#cb87-8"></a>memset<span class="op">(&</span>hints<span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="kw">sizeof</span> hints<span class="op">);</span></span>
|
|||
|
|
<span id="cb87-9"><a href="man-pages.html#cb87-9"></a>hints<span class="op">.</span>ai_family <span class="op">=</span> AF_UNSPEC<span class="op">;</span> <span class="co">// use IPv4 or IPv6, whichever</span></span>
|
|||
|
|
<span id="cb87-10"><a href="man-pages.html#cb87-10"></a>hints<span class="op">.</span>ai_socktype <span class="op">=</span> SOCK_STREAM<span class="op">;</span></span>
|
|||
|
|
<span id="cb87-11"><a href="man-pages.html#cb87-11"></a></span>
|
|||
|
|
<span id="cb87-12"><a href="man-pages.html#cb87-12"></a><span class="co">// we could put "80" instead on "http" on the next line:</span></span>
|
|||
|
|
<span id="cb87-13"><a href="man-pages.html#cb87-13"></a>getaddrinfo<span class="op">(</span><span class="st">"www.example.com"</span><span class="op">,</span> <span class="st">"http"</span><span class="op">,</span> <span class="op">&</span>hints<span class="op">,</span> <span class="op">&</span>res<span class="op">);</span></span>
|
|||
|
|
<span id="cb87-14"><a href="man-pages.html#cb87-14"></a></span>
|
|||
|
|
<span id="cb87-15"><a href="man-pages.html#cb87-15"></a><span class="co">// make a socket:</span></span>
|
|||
|
|
<span id="cb87-16"><a href="man-pages.html#cb87-16"></a></span>
|
|||
|
|
<span id="cb87-17"><a href="man-pages.html#cb87-17"></a>sockfd <span class="op">=</span> socket<span class="op">(</span>res<span class="op">-></span>ai_family<span class="op">,</span> res<span class="op">-></span>ai_socktype<span class="op">,</span> res<span class="op">-></span>ai_protocol<span class="op">);</span></span>
|
|||
|
|
<span id="cb87-18"><a href="man-pages.html#cb87-18"></a></span>
|
|||
|
|
<span id="cb87-19"><a href="man-pages.html#cb87-19"></a><span class="co">// connect it to the address and port we passed in to getaddrinfo():</span></span>
|
|||
|
|
<span id="cb87-20"><a href="man-pages.html#cb87-20"></a></span>
|
|||
|
|
<span id="cb87-21"><a href="man-pages.html#cb87-21"></a>connect<span class="op">(</span>sockfd<span class="op">,</span> res<span class="op">-></span>ai_addr<span class="op">,</span> res<span class="op">-></span>ai_addrlen<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-2">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#socketman"><code>socket()</code></a>, <a href="man-pages.html#bindman"><code>bind()</code></a></p>
|
|||
|
|
<h2 data-number="9.4" id="closeman"><span class="header-section-number">9.4</span> <code>close()</code></h2>
|
|||
|
|
<p></p>
|
|||
|
|
<p>Close a socket descriptor</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-3">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb88"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb88-1"><a href="man-pages.html#cb88-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><unistd.h></span></span>
|
|||
|
|
<span id="cb88-2"><a href="man-pages.html#cb88-2" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb88-3"><a href="man-pages.html#cb88-3" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> close<span class="op">(</span><span class="dt">int</span> s<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-3">Description</h3>
|
|||
|
|
<p>After you’ve finished using the socket for whatever demented scheme you have concocted and you don’t want to <code>send()</code> or <code>recv()</code> or, indeed, do <em>anything else</em> at all with the socket, you can <code>close()</code> it, and it’ll be freed up, never to be used again.</p>
|
|||
|
|
<p>The remote side can tell if this happens one of two ways. One: if the remote side calls <code>recv()</code>, it will return <code>0</code>. Two: if the remote side calls <code>send()</code>, it’ll receive a signal <code>SIGPIPE</code> and send() will return <code>-1</code> and <code>errno</code> will be set to <code>EPIPE</code>.</p>
|
|||
|
|
<p> <strong>Windows users</strong>: the function you need to use is called <code>closesocket()</code>, not <code>close()</code>. If you try to use <code>close()</code> on a socket descriptor, it’s possible Windows will get angry… And you wouldn’t like it when it’s angry.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-3">Return Value</h3>
|
|||
|
|
<p>Returns zero on success, or <code>-1</code> on error (and <code>errno</code> will be set accordingly).</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-3">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb89"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb89-1"><a href="man-pages.html#cb89-1"></a>s <span class="op">=</span> socket<span class="op">(</span>PF_INET<span class="op">,</span> SOCK_DGRAM<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb89-2"><a href="man-pages.html#cb89-2"></a><span class="op">.</span></span>
|
|||
|
|
<span id="cb89-3"><a href="man-pages.html#cb89-3"></a><span class="op">.</span></span>
|
|||
|
|
<span id="cb89-4"><a href="man-pages.html#cb89-4"></a><span class="op">.</span></span>
|
|||
|
|
<span id="cb89-5"><a href="man-pages.html#cb89-5"></a><span class="co">// a whole lotta stuff...*BRRRONNNN!*</span></span>
|
|||
|
|
<span id="cb89-6"><a href="man-pages.html#cb89-6"></a><span class="op">.</span></span>
|
|||
|
|
<span id="cb89-7"><a href="man-pages.html#cb89-7"></a><span class="op">.</span></span>
|
|||
|
|
<span id="cb89-8"><a href="man-pages.html#cb89-8"></a><span class="op">.</span></span>
|
|||
|
|
<span id="cb89-9"><a href="man-pages.html#cb89-9"></a>close<span class="op">(</span>s<span class="op">);</span> <span class="co">// not much to it, really.</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-3">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#socketman"><code>socket()</code></a>, <a href="man-pages.html#shutdownman"><code>shutdown()</code></a></p>
|
|||
|
|
<h2 data-number="9.5" id="getaddrinfoman"><span class="header-section-number">9.5</span> <code>getaddrinfo()</code>, <code>freeaddrinfo()</code>, <code>gai_strerror()</code></h2>
|
|||
|
|
<p> </p>
|
|||
|
|
<p>Get information about a host name and/or service and load up a <code>struct sockaddr</code> with the result.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-4">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb90"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb90-1"><a href="man-pages.html#cb90-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/types.h></span></span>
|
|||
|
|
<span id="cb90-2"><a href="man-pages.html#cb90-2" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb90-3"><a href="man-pages.html#cb90-3" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><netdb.h></span></span>
|
|||
|
|
<span id="cb90-4"><a href="man-pages.html#cb90-4" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb90-5"><a href="man-pages.html#cb90-5" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> getaddrinfo<span class="op">(</span><span class="dt">const</span> <span class="dt">char</span> <span class="op">*</span>nodename<span class="op">,</span> <span class="dt">const</span> <span class="dt">char</span> <span class="op">*</span>servname<span class="op">,</span></span>
|
|||
|
|
<span id="cb90-6"><a href="man-pages.html#cb90-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">const</span> <span class="kw">struct</span> addrinfo <span class="op">*</span>hints<span class="op">,</span> <span class="kw">struct</span> addrinfo <span class="op">**</span>res<span class="op">);</span></span>
|
|||
|
|
<span id="cb90-7"><a href="man-pages.html#cb90-7" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb90-8"><a href="man-pages.html#cb90-8" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> freeaddrinfo<span class="op">(</span><span class="kw">struct</span> addrinfo <span class="op">*</span>ai<span class="op">);</span></span>
|
|||
|
|
<span id="cb90-9"><a href="man-pages.html#cb90-9" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb90-10"><a href="man-pages.html#cb90-10" aria-hidden="true" tabindex="-1"></a><span class="dt">const</span> <span class="dt">char</span> <span class="op">*</span>gai_strerror<span class="op">(</span><span class="dt">int</span> ecode<span class="op">);</span></span>
|
|||
|
|
<span id="cb90-11"><a href="man-pages.html#cb90-11" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb90-12"><a href="man-pages.html#cb90-12" aria-hidden="true" tabindex="-1"></a><span class="kw">struct</span> addrinfo <span class="op">{</span></span>
|
|||
|
|
<span id="cb90-13"><a href="man-pages.html#cb90-13" aria-hidden="true" tabindex="-1"></a> <span class="dt">int</span> ai_flags<span class="op">;</span> <span class="co">// AI_PASSIVE, AI_CANONNAME, ...</span></span>
|
|||
|
|
<span id="cb90-14"><a href="man-pages.html#cb90-14" aria-hidden="true" tabindex="-1"></a> <span class="dt">int</span> ai_family<span class="op">;</span> <span class="co">// AF_xxx</span></span>
|
|||
|
|
<span id="cb90-15"><a href="man-pages.html#cb90-15" aria-hidden="true" tabindex="-1"></a> <span class="dt">int</span> ai_socktype<span class="op">;</span> <span class="co">// SOCK_xxx</span></span>
|
|||
|
|
<span id="cb90-16"><a href="man-pages.html#cb90-16" aria-hidden="true" tabindex="-1"></a> <span class="dt">int</span> ai_protocol<span class="op">;</span> <span class="co">// 0 (auto) or IPPROTO_TCP, IPPROTO_UDP </span></span>
|
|||
|
|
<span id="cb90-17"><a href="man-pages.html#cb90-17" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb90-18"><a href="man-pages.html#cb90-18" aria-hidden="true" tabindex="-1"></a> socklen_t ai_addrlen<span class="op">;</span> <span class="co">// length of ai_addr</span></span>
|
|||
|
|
<span id="cb90-19"><a href="man-pages.html#cb90-19" aria-hidden="true" tabindex="-1"></a> <span class="dt">char</span> <span class="op">*</span>ai_canonname<span class="op">;</span> <span class="co">// canonical name for nodename</span></span>
|
|||
|
|
<span id="cb90-20"><a href="man-pages.html#cb90-20" aria-hidden="true" tabindex="-1"></a> <span class="kw">struct</span> sockaddr <span class="op">*</span>ai_addr<span class="op">;</span> <span class="co">// binary address</span></span>
|
|||
|
|
<span id="cb90-21"><a href="man-pages.html#cb90-21" aria-hidden="true" tabindex="-1"></a> <span class="kw">struct</span> addrinfo <span class="op">*</span>ai_next<span class="op">;</span> <span class="co">// next structure in linked list</span></span>
|
|||
|
|
<span id="cb90-22"><a href="man-pages.html#cb90-22" aria-hidden="true" tabindex="-1"></a><span class="op">};</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-4">Description</h3>
|
|||
|
|
<p><code>getaddrinfo()</code> is an excellent function that will return information on a particular host name (such as its IP address) and load up a <code>struct sockaddr</code> for you, taking care of the gritty details (like if it’s IPv4 or IPv6). It replaces the old functions <code>gethostbyname()</code> and <code>getservbyname()</code>.The description, below, contains a lot of information that might be a little daunting, but actual usage is pretty simple. It might be worth it to check out the examples first.</p>
|
|||
|
|
<p>The host name that you’re interested in goes in the <code>nodename</code> parameter. The address can be either a host name, like “www.example.com”, or an IPv4 or IPv6 address (passed as a string). This parameter can also be <code>NULL</code> if you’re using the <code>AI_PASSIVE</code> flag (see below).</p>
|
|||
|
|
<p>The <code>servname</code> parameter is basically the port number. It can be a port number (passed as a string, like “80”), or it can be a service name, like “http” or “tftp” or “smtp” or “pop”, etc. Well-known service names can be found in the <a href="https://www.iana.org/assignments/port-numbers">IANA Port List</a><a href="footnotes.html#fn48" class="footnote-ref" id="fnref48" role="doc-noteref"><sup>48</sup></a> or in your <code>/etc/services</code> file.</p>
|
|||
|
|
<p>Lastly, for input parameters, we have <code>hints</code>. This is really where you get to define what the <code>getaddrinfo()</code> function is going to do. Zero the whole structure before use with <code>memset()</code>. Let’s take a look at the fields you need to set up before use.</p>
|
|||
|
|
<p>The <code>ai_flags</code> can be set to a variety of things, but here are a couple important ones. (Multiple flags can be specified by bitwise-ORing them together with the <code>|</code> operator). Check your man page for the complete list of flags.</p>
|
|||
|
|
<p><code>AI_CANONNAME</code> causes the <code>ai_canonname</code> of the result to the filled out with the host’s canonical (real) name. <code>AI_PASSIVE</code> causes the result’s IP address to be filled out with <code>INADDR_ANY</code> (IPv4) or <code>in6addr_any</code> (IPv6); this causes a subsequent call to <code>bind()</code> to auto-fill the IP address of the <code>struct sockaddr</code> with the address of the current host. That’s excellent for setting up a server when you don’t want to hardcode the address.</p>
|
|||
|
|
<p>If you do use the <code>AI_PASSIVE</code>, flag, then you can pass <code>NULL</code> in the <code>nodename</code> (since <code>bind()</code> will fill it in for you later).</p>
|
|||
|
|
<p>Continuing on with the input parameters, you’ll likely want to set <code>ai_family</code> to <code>AF_UNSPEC</code> which tells <code>getaddrinfo()</code> to look for both IPv4 and IPv6 addresses. You can also restrict yourself to one or the other with <code>AF_INET</code> or <code>AF_INET6</code>.</p>
|
|||
|
|
<p>Next, the <code>socktype</code> field should be set to <code>SOCK_STREAM</code> or <code>SOCK_DGRAM</code>, depending on which type of socket you want.</p>
|
|||
|
|
<p>Finally, just leave <code>ai_protocol</code> at <code>0</code> to automatically choose your protocol type.</p>
|
|||
|
|
<p>Now, after you get all that stuff in there, you can <em>finally</em> make the call to <code>getaddrinfo()</code>!</p>
|
|||
|
|
<p>Of course, this is where the fun begins. The <code>res</code> will now point to a linked list of <code>struct addrinfo</code>s, and you can go through this list to get all the addresses that match what you passed in with the hints.</p>
|
|||
|
|
<p>Now, it’s possible to get some addresses that don’t work for one reason or another, so what the Linux man page does is loops through the list doing a call to <code>socket()</code> and <code>connect()</code> (or <code>bind()</code> if you’re setting up a server with the <code>AI_PASSIVE</code> flag) until it succeeds.</p>
|
|||
|
|
<p>Finally, when you’re done with the linked list, you need to call <code>freeaddrinfo()</code> to free up the memory (or it will be leaked, and Some People will get upset).</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-4">Return Value</h3>
|
|||
|
|
<p>Returns zero on success, or nonzero on error. If it returns nonzero, you can use the function <code>gai_strerror()</code> to get a printable version of the error code in the return value.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-4">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb91"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb91-1"><a href="man-pages.html#cb91-1"></a><span class="co">// code for a client connecting to a server</span></span>
|
|||
|
|
<span id="cb91-2"><a href="man-pages.html#cb91-2"></a><span class="co">// namely a stream socket to www.example.com on port 80 (http)</span></span>
|
|||
|
|
<span id="cb91-3"><a href="man-pages.html#cb91-3"></a><span class="co">// either IPv4 or IPv6</span></span>
|
|||
|
|
<span id="cb91-4"><a href="man-pages.html#cb91-4"></a></span>
|
|||
|
|
<span id="cb91-5"><a href="man-pages.html#cb91-5"></a><span class="dt">int</span> sockfd<span class="op">;</span> </span>
|
|||
|
|
<span id="cb91-6"><a href="man-pages.html#cb91-6"></a><span class="kw">struct</span> addrinfo hints<span class="op">,</span> <span class="op">*</span>servinfo<span class="op">,</span> <span class="op">*</span>p<span class="op">;</span></span>
|
|||
|
|
<span id="cb91-7"><a href="man-pages.html#cb91-7"></a><span class="dt">int</span> rv<span class="op">;</span></span>
|
|||
|
|
<span id="cb91-8"><a href="man-pages.html#cb91-8"></a></span>
|
|||
|
|
<span id="cb91-9"><a href="man-pages.html#cb91-9"></a>memset<span class="op">(&</span>hints<span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="kw">sizeof</span> hints<span class="op">);</span></span>
|
|||
|
|
<span id="cb91-10"><a href="man-pages.html#cb91-10"></a>hints<span class="op">.</span>ai_family <span class="op">=</span> AF_UNSPEC<span class="op">;</span> <span class="co">// use AF_INET6 to force IPv6</span></span>
|
|||
|
|
<span id="cb91-11"><a href="man-pages.html#cb91-11"></a>hints<span class="op">.</span>ai_socktype <span class="op">=</span> SOCK_STREAM<span class="op">;</span></span>
|
|||
|
|
<span id="cb91-12"><a href="man-pages.html#cb91-12"></a></span>
|
|||
|
|
<span id="cb91-13"><a href="man-pages.html#cb91-13"></a><span class="cf">if</span> <span class="op">((</span>rv <span class="op">=</span> getaddrinfo<span class="op">(</span><span class="st">"www.example.com"</span><span class="op">,</span> <span class="st">"http"</span><span class="op">,</span> <span class="op">&</span>hints<span class="op">,</span> <span class="op">&</span>servinfo<span class="op">))</span> <span class="op">!=</span> <span class="dv">0</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb91-14"><a href="man-pages.html#cb91-14"></a> fprintf<span class="op">(</span>stderr<span class="op">,</span> <span class="st">"getaddrinfo: </span><span class="sc">%s\n</span><span class="st">"</span><span class="op">,</span> gai_strerror<span class="op">(</span>rv<span class="op">));</span></span>
|
|||
|
|
<span id="cb91-15"><a href="man-pages.html#cb91-15"></a> exit<span class="op">(</span><span class="dv">1</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb91-16"><a href="man-pages.html#cb91-16"></a><span class="op">}</span></span>
|
|||
|
|
<span id="cb91-17"><a href="man-pages.html#cb91-17"></a></span>
|
|||
|
|
<span id="cb91-18"><a href="man-pages.html#cb91-18"></a><span class="co">// loop through all the results and connect to the first we can</span></span>
|
|||
|
|
<span id="cb91-19"><a href="man-pages.html#cb91-19"></a><span class="cf">for</span><span class="op">(</span>p <span class="op">=</span> servinfo<span class="op">;</span> p <span class="op">!=</span> NULL<span class="op">;</span> p <span class="op">=</span> p<span class="op">-></span>ai_next<span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb91-20"><a href="man-pages.html#cb91-20"></a> <span class="cf">if</span> <span class="op">((</span>sockfd <span class="op">=</span> socket<span class="op">(</span>p<span class="op">-></span>ai_family<span class="op">,</span> p<span class="op">-></span>ai_socktype<span class="op">,</span></span>
|
|||
|
|
<span id="cb91-21"><a href="man-pages.html#cb91-21"></a> p<span class="op">-></span>ai_protocol<span class="op">))</span> <span class="op">==</span> <span class="op">-</span><span class="dv">1</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb91-22"><a href="man-pages.html#cb91-22"></a> perror<span class="op">(</span><span class="st">"socket"</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb91-23"><a href="man-pages.html#cb91-23"></a> <span class="cf">continue</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb91-24"><a href="man-pages.html#cb91-24"></a> <span class="op">}</span></span>
|
|||
|
|
<span id="cb91-25"><a href="man-pages.html#cb91-25"></a></span>
|
|||
|
|
<span id="cb91-26"><a href="man-pages.html#cb91-26"></a> <span class="cf">if</span> <span class="op">(</span>connect<span class="op">(</span>sockfd<span class="op">,</span> p<span class="op">-></span>ai_addr<span class="op">,</span> p<span class="op">-></span>ai_addrlen<span class="op">)</span> <span class="op">==</span> <span class="op">-</span><span class="dv">1</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb91-27"><a href="man-pages.html#cb91-27"></a> perror<span class="op">(</span><span class="st">"connect"</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb91-28"><a href="man-pages.html#cb91-28"></a> close<span class="op">(</span>sockfd<span class="op">);</span></span>
|
|||
|
|
<span id="cb91-29"><a href="man-pages.html#cb91-29"></a> <span class="cf">continue</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb91-30"><a href="man-pages.html#cb91-30"></a> <span class="op">}</span></span>
|
|||
|
|
<span id="cb91-31"><a href="man-pages.html#cb91-31"></a></span>
|
|||
|
|
<span id="cb91-32"><a href="man-pages.html#cb91-32"></a> <span class="cf">break</span><span class="op">;</span> <span class="co">// if we get here, we must have connected successfully</span></span>
|
|||
|
|
<span id="cb91-33"><a href="man-pages.html#cb91-33"></a><span class="op">}</span></span>
|
|||
|
|
<span id="cb91-34"><a href="man-pages.html#cb91-34"></a></span>
|
|||
|
|
<span id="cb91-35"><a href="man-pages.html#cb91-35"></a><span class="cf">if</span> <span class="op">(</span>p <span class="op">==</span> NULL<span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb91-36"><a href="man-pages.html#cb91-36"></a> <span class="co">// looped off the end of the list with no connection</span></span>
|
|||
|
|
<span id="cb91-37"><a href="man-pages.html#cb91-37"></a> fprintf<span class="op">(</span>stderr<span class="op">,</span> <span class="st">"failed to connect</span><span class="sc">\n</span><span class="st">"</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb91-38"><a href="man-pages.html#cb91-38"></a> exit<span class="op">(</span><span class="dv">2</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb91-39"><a href="man-pages.html#cb91-39"></a><span class="op">}</span></span>
|
|||
|
|
<span id="cb91-40"><a href="man-pages.html#cb91-40"></a></span>
|
|||
|
|
<span id="cb91-41"><a href="man-pages.html#cb91-41"></a>freeaddrinfo<span class="op">(</span>servinfo<span class="op">);</span> <span class="co">// all done with this structure</span></span></code></pre></div>
|
|||
|
|
<div class="sourceCode" id="cb92"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb92-1"><a href="man-pages.html#cb92-1"></a><span class="co">// code for a server waiting for connections</span></span>
|
|||
|
|
<span id="cb92-2"><a href="man-pages.html#cb92-2"></a><span class="co">// namely a stream socket on port 3490, on this host's IP</span></span>
|
|||
|
|
<span id="cb92-3"><a href="man-pages.html#cb92-3"></a><span class="co">// either IPv4 or IPv6.</span></span>
|
|||
|
|
<span id="cb92-4"><a href="man-pages.html#cb92-4"></a></span>
|
|||
|
|
<span id="cb92-5"><a href="man-pages.html#cb92-5"></a><span class="dt">int</span> sockfd<span class="op">;</span> </span>
|
|||
|
|
<span id="cb92-6"><a href="man-pages.html#cb92-6"></a><span class="kw">struct</span> addrinfo hints<span class="op">,</span> <span class="op">*</span>servinfo<span class="op">,</span> <span class="op">*</span>p<span class="op">;</span></span>
|
|||
|
|
<span id="cb92-7"><a href="man-pages.html#cb92-7"></a><span class="dt">int</span> rv<span class="op">;</span></span>
|
|||
|
|
<span id="cb92-8"><a href="man-pages.html#cb92-8"></a></span>
|
|||
|
|
<span id="cb92-9"><a href="man-pages.html#cb92-9"></a>memset<span class="op">(&</span>hints<span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="kw">sizeof</span> hints<span class="op">);</span></span>
|
|||
|
|
<span id="cb92-10"><a href="man-pages.html#cb92-10"></a>hints<span class="op">.</span>ai_family <span class="op">=</span> AF_UNSPEC<span class="op">;</span> <span class="co">// use AF_INET6 to force IPv6</span></span>
|
|||
|
|
<span id="cb92-11"><a href="man-pages.html#cb92-11"></a>hints<span class="op">.</span>ai_socktype <span class="op">=</span> SOCK_STREAM<span class="op">;</span></span>
|
|||
|
|
<span id="cb92-12"><a href="man-pages.html#cb92-12"></a>hints<span class="op">.</span>ai_flags <span class="op">=</span> AI_PASSIVE<span class="op">;</span> <span class="co">// use my IP address</span></span>
|
|||
|
|
<span id="cb92-13"><a href="man-pages.html#cb92-13"></a></span>
|
|||
|
|
<span id="cb92-14"><a href="man-pages.html#cb92-14"></a><span class="cf">if</span> <span class="op">((</span>rv <span class="op">=</span> getaddrinfo<span class="op">(</span>NULL<span class="op">,</span> <span class="st">"3490"</span><span class="op">,</span> <span class="op">&</span>hints<span class="op">,</span> <span class="op">&</span>servinfo<span class="op">))</span> <span class="op">!=</span> <span class="dv">0</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb92-15"><a href="man-pages.html#cb92-15"></a> fprintf<span class="op">(</span>stderr<span class="op">,</span> <span class="st">"getaddrinfo: </span><span class="sc">%s\n</span><span class="st">"</span><span class="op">,</span> gai_strerror<span class="op">(</span>rv<span class="op">));</span></span>
|
|||
|
|
<span id="cb92-16"><a href="man-pages.html#cb92-16"></a> exit<span class="op">(</span><span class="dv">1</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb92-17"><a href="man-pages.html#cb92-17"></a><span class="op">}</span></span>
|
|||
|
|
<span id="cb92-18"><a href="man-pages.html#cb92-18"></a></span>
|
|||
|
|
<span id="cb92-19"><a href="man-pages.html#cb92-19"></a><span class="co">// loop through all the results and bind to the first we can</span></span>
|
|||
|
|
<span id="cb92-20"><a href="man-pages.html#cb92-20"></a><span class="cf">for</span><span class="op">(</span>p <span class="op">=</span> servinfo<span class="op">;</span> p <span class="op">!=</span> NULL<span class="op">;</span> p <span class="op">=</span> p<span class="op">-></span>ai_next<span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb92-21"><a href="man-pages.html#cb92-21"></a> <span class="cf">if</span> <span class="op">((</span>sockfd <span class="op">=</span> socket<span class="op">(</span>p<span class="op">-></span>ai_family<span class="op">,</span> p<span class="op">-></span>ai_socktype<span class="op">,</span></span>
|
|||
|
|
<span id="cb92-22"><a href="man-pages.html#cb92-22"></a> p<span class="op">-></span>ai_protocol<span class="op">))</span> <span class="op">==</span> <span class="op">-</span><span class="dv">1</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb92-23"><a href="man-pages.html#cb92-23"></a> perror<span class="op">(</span><span class="st">"socket"</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb92-24"><a href="man-pages.html#cb92-24"></a> <span class="cf">continue</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb92-25"><a href="man-pages.html#cb92-25"></a> <span class="op">}</span></span>
|
|||
|
|
<span id="cb92-26"><a href="man-pages.html#cb92-26"></a></span>
|
|||
|
|
<span id="cb92-27"><a href="man-pages.html#cb92-27"></a> <span class="cf">if</span> <span class="op">(</span>bind<span class="op">(</span>sockfd<span class="op">,</span> p<span class="op">-></span>ai_addr<span class="op">,</span> p<span class="op">-></span>ai_addrlen<span class="op">)</span> <span class="op">==</span> <span class="op">-</span><span class="dv">1</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb92-28"><a href="man-pages.html#cb92-28"></a> close<span class="op">(</span>sockfd<span class="op">);</span></span>
|
|||
|
|
<span id="cb92-29"><a href="man-pages.html#cb92-29"></a> perror<span class="op">(</span><span class="st">"bind"</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb92-30"><a href="man-pages.html#cb92-30"></a> <span class="cf">continue</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb92-31"><a href="man-pages.html#cb92-31"></a> <span class="op">}</span></span>
|
|||
|
|
<span id="cb92-32"><a href="man-pages.html#cb92-32"></a></span>
|
|||
|
|
<span id="cb92-33"><a href="man-pages.html#cb92-33"></a> <span class="cf">break</span><span class="op">;</span> <span class="co">// if we get here, we must have connected successfully</span></span>
|
|||
|
|
<span id="cb92-34"><a href="man-pages.html#cb92-34"></a><span class="op">}</span></span>
|
|||
|
|
<span id="cb92-35"><a href="man-pages.html#cb92-35"></a></span>
|
|||
|
|
<span id="cb92-36"><a href="man-pages.html#cb92-36"></a><span class="cf">if</span> <span class="op">(</span>p <span class="op">==</span> NULL<span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb92-37"><a href="man-pages.html#cb92-37"></a> <span class="co">// looped off the end of the list with no successful bind</span></span>
|
|||
|
|
<span id="cb92-38"><a href="man-pages.html#cb92-38"></a> fprintf<span class="op">(</span>stderr<span class="op">,</span> <span class="st">"failed to bind socket</span><span class="sc">\n</span><span class="st">"</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb92-39"><a href="man-pages.html#cb92-39"></a> exit<span class="op">(</span><span class="dv">2</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb92-40"><a href="man-pages.html#cb92-40"></a><span class="op">}</span></span>
|
|||
|
|
<span id="cb92-41"><a href="man-pages.html#cb92-41"></a></span>
|
|||
|
|
<span id="cb92-42"><a href="man-pages.html#cb92-42"></a>freeaddrinfo<span class="op">(</span>servinfo<span class="op">);</span> <span class="co">// all done with this structure</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-4">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#gethostbynameman"><code>gethostbyname()</code></a>, <a href="man-pages.html#getnameinfoman"><code>getnameinfo()</code></a></p>
|
|||
|
|
<h2 data-number="9.6" id="gethostnameman"><span class="header-section-number">9.6</span> <code>gethostname()</code></h2>
|
|||
|
|
<p></p>
|
|||
|
|
<p>Returns the name of the system</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-5">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb93"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb93-1"><a href="man-pages.html#cb93-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/unistd.h></span></span>
|
|||
|
|
<span id="cb93-2"><a href="man-pages.html#cb93-2" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb93-3"><a href="man-pages.html#cb93-3" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> gethostname<span class="op">(</span><span class="dt">char</span> <span class="op">*</span>name<span class="op">,</span> <span class="dt">size_t</span> len<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-5">Description</h3>
|
|||
|
|
<p>Your system has a name. They all do. This is a slightly more Unixy thing than the rest of the networky stuff we’ve been talking about, but it still has its uses.</p>
|
|||
|
|
<p>For instance, you can get your host name, and then call <code>gethostbyname()</code> to find out your IP address.</p>
|
|||
|
|
<p>The parameter <code>name</code> should point to a buffer that will hold the host name, and <code>len</code> is the size of that buffer in bytes. <code>gethostname()</code> won’t overwrite the end of the buffer (it might return an error, or it might just stop writing), and it will <code>NUL</code>-terminate the string if there’s room for it in the buffer.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-5">Return Value</h3>
|
|||
|
|
<p>Returns zero on success, or <code>-1</code> on error (and <code>errno</code> will be set accordingly).</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-5">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb94"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb94-1"><a href="man-pages.html#cb94-1"></a><span class="dt">char</span> hostname<span class="op">[</span><span class="dv">128</span><span class="op">];</span></span>
|
|||
|
|
<span id="cb94-2"><a href="man-pages.html#cb94-2"></a></span>
|
|||
|
|
<span id="cb94-3"><a href="man-pages.html#cb94-3"></a>gethostname<span class="op">(</span>hostname<span class="op">,</span> <span class="kw">sizeof</span> hostname<span class="op">);</span></span>
|
|||
|
|
<span id="cb94-4"><a href="man-pages.html#cb94-4"></a>printf<span class="op">(</span><span class="st">"My hostname: </span><span class="sc">%s\n</span><span class="st">"</span><span class="op">,</span> hostname<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-5">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#gethostbynameman"><code>gethostbyname()</code></a></p>
|
|||
|
|
<h2 data-number="9.7" id="gethostbynameman"><span class="header-section-number">9.7</span> <code>gethostbyname()</code>, <code>gethostbyaddr()</code></h2>
|
|||
|
|
<p> </p>
|
|||
|
|
<p>Get an IP address for a hostname, or vice-versa</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-6">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb95"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb95-1"><a href="man-pages.html#cb95-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb95-2"><a href="man-pages.html#cb95-2" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><netdb.h></span></span>
|
|||
|
|
<span id="cb95-3"><a href="man-pages.html#cb95-3" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb95-4"><a href="man-pages.html#cb95-4" aria-hidden="true" tabindex="-1"></a><span class="kw">struct</span> hostent <span class="op">*</span>gethostbyname<span class="op">(</span><span class="dt">const</span> <span class="dt">char</span> <span class="op">*</span>name<span class="op">);</span> <span class="co">// </span><span class="al">DEPRECATED</span><span class="co">!</span></span>
|
|||
|
|
<span id="cb95-5"><a href="man-pages.html#cb95-5" aria-hidden="true" tabindex="-1"></a><span class="kw">struct</span> hostent <span class="op">*</span>gethostbyaddr<span class="op">(</span><span class="dt">const</span> <span class="dt">char</span> <span class="op">*</span>addr<span class="op">,</span> <span class="dt">int</span> len<span class="op">,</span> <span class="dt">int</span> type<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-6">Description</h3>
|
|||
|
|
<p><em>PLEASE NOTE: these two functions are superseded by <code>getaddrinfo()</code> and <code>getnameinfo()</code>!</em> In particular, <code>gethostbyname()</code> doesn’t work well with IPv6.</p>
|
|||
|
|
<p>These functions map back and forth between host names and IP addresses. For instance, if you have “www.example.com”, you can use <code>gethostbyname()</code> to get its IP address and store it in a <code>struct in_addr</code>.</p>
|
|||
|
|
<p>Conversely, if you have a <code>struct in_addr</code> or a <code>struct in6_addr</code>, you can use <code>gethostbyaddr()</code> to get the hostname back. <code>gethostbyaddr()</code> <em>is</em> IPv6 compatible, but you should use the newer shinier <code>getnameinfo()</code> instead.</p>
|
|||
|
|
<p>(If you have a string containing an IP address in dots-and-numbers format that you want to look up the hostname of, you’d be better off using <code>getaddrinfo()</code> with the <code>AI_CANONNAME</code> flag.)</p>
|
|||
|
|
<p><code>gethostbyname()</code> takes a string like “www.yahoo.com”, and returns a <code>struct hostent</code> which contains tons of information, including the IP address. (Other information is the official host name, a list of aliases, the address type, the length of the addresses, and the list of addresses—it’s a general-purpose structure that’s pretty easy to use for our specific purposes once you see how.)</p>
|
|||
|
|
<p><code>gethostbyaddr()</code> takes a <code>struct in_addr</code> or <code>struct in6_addr</code> and brings you up a corresponding host name (if there is one), so it’s sort of the reverse of <code>gethostbyname()</code>. As for parameters, even though <code>addr</code> is a <code>char*</code>, you actually want to pass in a pointer to a <code>struct in_addr</code>. <code>len</code> should be <code>sizeof(struct in_addr)</code>, and <code>type</code> should be <code>AF_INET</code>.</p>
|
|||
|
|
<p>So what is this <code>struct hostent</code> that gets returned? It has a number of fields that contain information about the host in question.</p>
|
|||
|
|
<table>
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 30%" />
|
|||
|
|
<col style="width: 69%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="header">
|
|||
|
|
<th>Field</th>
|
|||
|
|
<th>Description</th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>char *h_name</code></td>
|
|||
|
|
<td>The real canonical host name.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>char **h_aliases</code></td>
|
|||
|
|
<td>A list of aliases that can be accessed with arrays—the last element is <code>NULL</code></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>int h_addrtype</code></td>
|
|||
|
|
<td>The result’s address type, which really should be <code>AF_INET</code> for our purposes.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>int length</code></td>
|
|||
|
|
<td>The length of the addresses in bytes, which is 4 for IP (version 4) addresses.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>char **h_addr_list</code></td>
|
|||
|
|
<td>A list of IP addresses for this host. Although this is a <code>char**</code>, it’s really an array of <code>struct in_addr*</code>s in disguise. The last array element is <code>NULL</code>.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>h_addr</code></td>
|
|||
|
|
<td>A commonly defined alias for <code>h_addr_list[0]</code>. If you just want any old IP address for this host (yeah, they can have more than one) just use this field.</td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-6">Return Value</h3>
|
|||
|
|
<p>Returns a pointer to a resultant <code>struct hostent</code> on success, or <code>NULL</code> on error.</p>
|
|||
|
|
<p>Instead of the normal <code>perror()</code> and all that stuff you’d normally use for error reporting, these functions have parallel results in the variable <code>h_errno</code>, which can be printed using the functions <code>herror()</code> or <code>hstrerror()</code>. These work just like the classic <code>errno</code>, <code>perror()</code>, and <code>strerror()</code> functions you’re used to.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-6">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb96"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb96-1"><a href="man-pages.html#cb96-1"></a><span class="co">// THIS IS A </span><span class="al">DEPRECATED</span><span class="co"> METHOD OF GETTING HOST NAMES</span></span>
|
|||
|
|
<span id="cb96-2"><a href="man-pages.html#cb96-2"></a><span class="co">// use getaddrinfo() instead!</span></span>
|
|||
|
|
<span id="cb96-3"><a href="man-pages.html#cb96-3"></a></span>
|
|||
|
|
<span id="cb96-4"><a href="man-pages.html#cb96-4"></a><span class="pp">#include </span><span class="im"><stdio.h></span></span>
|
|||
|
|
<span id="cb96-5"><a href="man-pages.html#cb96-5"></a><span class="pp">#include </span><span class="im"><errno.h></span></span>
|
|||
|
|
<span id="cb96-6"><a href="man-pages.html#cb96-6"></a><span class="pp">#include </span><span class="im"><netdb.h></span></span>
|
|||
|
|
<span id="cb96-7"><a href="man-pages.html#cb96-7"></a><span class="pp">#include </span><span class="im"><sys/types.h></span></span>
|
|||
|
|
<span id="cb96-8"><a href="man-pages.html#cb96-8"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb96-9"><a href="man-pages.html#cb96-9"></a><span class="pp">#include </span><span class="im"><netinet/in.h></span></span>
|
|||
|
|
<span id="cb96-10"><a href="man-pages.html#cb96-10"></a><span class="pp">#include </span><span class="im"><arpa/inet.h></span></span>
|
|||
|
|
<span id="cb96-11"><a href="man-pages.html#cb96-11"></a></span>
|
|||
|
|
<span id="cb96-12"><a href="man-pages.html#cb96-12"></a><span class="dt">int</span> main<span class="op">(</span><span class="dt">int</span> argc<span class="op">,</span> <span class="dt">char</span> <span class="op">*</span>argv<span class="op">[])</span></span>
|
|||
|
|
<span id="cb96-13"><a href="man-pages.html#cb96-13"></a><span class="op">{</span></span>
|
|||
|
|
<span id="cb96-14"><a href="man-pages.html#cb96-14"></a> <span class="dt">int</span> i<span class="op">;</span></span>
|
|||
|
|
<span id="cb96-15"><a href="man-pages.html#cb96-15"></a> <span class="kw">struct</span> hostent <span class="op">*</span>he<span class="op">;</span></span>
|
|||
|
|
<span id="cb96-16"><a href="man-pages.html#cb96-16"></a> <span class="kw">struct</span> in_addr <span class="op">**</span>addr_list<span class="op">;</span></span>
|
|||
|
|
<span id="cb96-17"><a href="man-pages.html#cb96-17"></a></span>
|
|||
|
|
<span id="cb96-18"><a href="man-pages.html#cb96-18"></a> <span class="cf">if</span> <span class="op">(</span>argc <span class="op">!=</span> <span class="dv">2</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb96-19"><a href="man-pages.html#cb96-19"></a> fprintf<span class="op">(</span>stderr<span class="op">,</span><span class="st">"usage: ghbn hostname</span><span class="sc">\n</span><span class="st">"</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb96-20"><a href="man-pages.html#cb96-20"></a> <span class="cf">return</span> <span class="dv">1</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb96-21"><a href="man-pages.html#cb96-21"></a> <span class="op">}</span></span>
|
|||
|
|
<span id="cb96-22"><a href="man-pages.html#cb96-22"></a></span>
|
|||
|
|
<span id="cb96-23"><a href="man-pages.html#cb96-23"></a> <span class="cf">if</span> <span class="op">((</span>he <span class="op">=</span> gethostbyname<span class="op">(</span>argv<span class="op">[</span><span class="dv">1</span><span class="op">]))</span> <span class="op">==</span> NULL<span class="op">)</span> <span class="op">{</span> <span class="co">// get the host info</span></span>
|
|||
|
|
<span id="cb96-24"><a href="man-pages.html#cb96-24"></a> herror<span class="op">(</span><span class="st">"gethostbyname"</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb96-25"><a href="man-pages.html#cb96-25"></a> <span class="cf">return</span> <span class="dv">2</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb96-26"><a href="man-pages.html#cb96-26"></a> <span class="op">}</span></span>
|
|||
|
|
<span id="cb96-27"><a href="man-pages.html#cb96-27"></a></span>
|
|||
|
|
<span id="cb96-28"><a href="man-pages.html#cb96-28"></a> <span class="co">// print information about this host:</span></span>
|
|||
|
|
<span id="cb96-29"><a href="man-pages.html#cb96-29"></a> printf<span class="op">(</span><span class="st">"Official name is: </span><span class="sc">%s\n</span><span class="st">"</span><span class="op">,</span> he<span class="op">-></span>h_name<span class="op">);</span></span>
|
|||
|
|
<span id="cb96-30"><a href="man-pages.html#cb96-30"></a> printf<span class="op">(</span><span class="st">" IP addresses: "</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb96-31"><a href="man-pages.html#cb96-31"></a> addr_list <span class="op">=</span> <span class="op">(</span><span class="kw">struct</span> in_addr <span class="op">**)</span>he<span class="op">-></span>h_addr_list<span class="op">;</span></span>
|
|||
|
|
<span id="cb96-32"><a href="man-pages.html#cb96-32"></a> <span class="cf">for</span><span class="op">(</span>i <span class="op">=</span> <span class="dv">0</span><span class="op">;</span> addr_list<span class="op">[</span>i<span class="op">]</span> <span class="op">!=</span> NULL<span class="op">;</span> i<span class="op">++)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb96-33"><a href="man-pages.html#cb96-33"></a> printf<span class="op">(</span><span class="st">"</span><span class="sc">%s</span><span class="st"> "</span><span class="op">,</span> inet_ntoa<span class="op">(*</span>addr_list<span class="op">[</span>i<span class="op">]));</span></span>
|
|||
|
|
<span id="cb96-34"><a href="man-pages.html#cb96-34"></a> <span class="op">}</span></span>
|
|||
|
|
<span id="cb96-35"><a href="man-pages.html#cb96-35"></a> printf<span class="op">(</span><span class="st">"</span><span class="sc">\n</span><span class="st">"</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb96-36"><a href="man-pages.html#cb96-36"></a></span>
|
|||
|
|
<span id="cb96-37"><a href="man-pages.html#cb96-37"></a> <span class="cf">return</span> <span class="dv">0</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb96-38"><a href="man-pages.html#cb96-38"></a><span class="op">}</span></span></code></pre></div>
|
|||
|
|
<div class="sourceCode" id="cb97"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb97-1"><a href="man-pages.html#cb97-1"></a><span class="co">// THIS HAS BEEN SUPERSEDED</span></span>
|
|||
|
|
<span id="cb97-2"><a href="man-pages.html#cb97-2"></a><span class="co">// use getnameinfo() instead!</span></span>
|
|||
|
|
<span id="cb97-3"><a href="man-pages.html#cb97-3"></a></span>
|
|||
|
|
<span id="cb97-4"><a href="man-pages.html#cb97-4"></a><span class="kw">struct</span> hostent <span class="op">*</span>he<span class="op">;</span></span>
|
|||
|
|
<span id="cb97-5"><a href="man-pages.html#cb97-5"></a><span class="kw">struct</span> in_addr ipv4addr<span class="op">;</span></span>
|
|||
|
|
<span id="cb97-6"><a href="man-pages.html#cb97-6"></a><span class="kw">struct</span> in6_addr ipv6addr<span class="op">;</span></span>
|
|||
|
|
<span id="cb97-7"><a href="man-pages.html#cb97-7"></a></span>
|
|||
|
|
<span id="cb97-8"><a href="man-pages.html#cb97-8"></a>inet_pton<span class="op">(</span>AF_INET<span class="op">,</span> <span class="st">"192.0.2.34"</span><span class="op">,</span> <span class="op">&</span>ipv4addr<span class="op">);</span></span>
|
|||
|
|
<span id="cb97-9"><a href="man-pages.html#cb97-9"></a>he <span class="op">=</span> gethostbyaddr<span class="op">(&</span>ipv4addr<span class="op">,</span> <span class="kw">sizeof</span> ipv4addr<span class="op">,</span> AF_INET<span class="op">);</span></span>
|
|||
|
|
<span id="cb97-10"><a href="man-pages.html#cb97-10"></a>printf<span class="op">(</span><span class="st">"Host name: </span><span class="sc">%s\n</span><span class="st">"</span><span class="op">,</span> he<span class="op">-></span>h_name<span class="op">);</span></span>
|
|||
|
|
<span id="cb97-11"><a href="man-pages.html#cb97-11"></a></span>
|
|||
|
|
<span id="cb97-12"><a href="man-pages.html#cb97-12"></a>inet_pton<span class="op">(</span>AF_INET6<span class="op">,</span> <span class="st">"2001:db8:63b3:1::beef"</span><span class="op">,</span> <span class="op">&</span>ipv6addr<span class="op">);</span></span>
|
|||
|
|
<span id="cb97-13"><a href="man-pages.html#cb97-13"></a>he <span class="op">=</span> gethostbyaddr<span class="op">(&</span>ipv6addr<span class="op">,</span> <span class="kw">sizeof</span> ipv6addr<span class="op">,</span> AF_INET6<span class="op">);</span></span>
|
|||
|
|
<span id="cb97-14"><a href="man-pages.html#cb97-14"></a>printf<span class="op">(</span><span class="st">"Host name: </span><span class="sc">%s\n</span><span class="st">"</span><span class="op">,</span> he<span class="op">-></span>h_name<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-6">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#getaddrinfoman"><code>getaddrinfo()</code></a>, <a href="man-pages.html#getnameinfoman"><code>getnameinfo()</code></a>, <a href="man-pages.html#gethostnameman"><code>gethostname()</code></a>, <a href="man-pages.html#errnoman"><code>errno</code></a>, <a href="man-pages.html#perrorman"><code>perror()</code></a>, <a href="man-pages.html#perrorman"><code>strerror()</code></a>, <a href="man-pages.html#structsockaddrman"><code>struct in_addr</code></a></p>
|
|||
|
|
<h2 data-number="9.8" id="getnameinfoman"><span class="header-section-number">9.8</span> <code>getnameinfo()</code></h2>
|
|||
|
|
<p></p>
|
|||
|
|
<p>Look up the host name and service name information for a given <code>struct sockaddr</code>.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-7">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb98"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb98-1"><a href="man-pages.html#cb98-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb98-2"><a href="man-pages.html#cb98-2" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><netdb.h></span></span>
|
|||
|
|
<span id="cb98-3"><a href="man-pages.html#cb98-3" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb98-4"><a href="man-pages.html#cb98-4" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> getnameinfo<span class="op">(</span><span class="dt">const</span> <span class="kw">struct</span> sockaddr <span class="op">*</span>sa<span class="op">,</span> socklen_t salen<span class="op">,</span></span>
|
|||
|
|
<span id="cb98-5"><a href="man-pages.html#cb98-5" aria-hidden="true" tabindex="-1"></a> <span class="dt">char</span> <span class="op">*</span>host<span class="op">,</span> <span class="dt">size_t</span> hostlen<span class="op">,</span></span>
|
|||
|
|
<span id="cb98-6"><a href="man-pages.html#cb98-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">char</span> <span class="op">*</span>serv<span class="op">,</span> <span class="dt">size_t</span> servlen<span class="op">,</span> <span class="dt">int</span> flags<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-7">Description</h3>
|
|||
|
|
<p>This function is the opposite of <code>getaddrinfo()</code>, that is, this function takes an already loaded <code>struct sockaddr</code> and does a name and service name lookup on it. It replaces the old <code>gethostbyaddr()</code> and <code>getservbyport()</code> functions.</p>
|
|||
|
|
<p>You have to pass in a pointer to a <code>struct sockaddr</code> (which in actuality is probably a <code>struct sockaddr_in</code> or <code>struct sockaddr_in6</code> that you’ve cast) in the <code>sa</code> parameter, and the length of that <code>struct</code> in the <code>salen</code>.</p>
|
|||
|
|
<p>The resultant host name and service name will be written to the area pointed to by the <code>host</code> and <code>serv</code> parameters. Of course, you have to specify the max lengths of these buffers in <code>hostlen</code> and <code>servlen</code>.</p>
|
|||
|
|
<p>Finally, there are several flags you can pass, but here a a couple good ones. <code>NI_NOFQDN</code> will cause the <code>host</code> to only contain the host name, not the whole domain name. <code>NI_NAMEREQD</code> will cause the function to fail if the name cannot be found with a DNS lookup (if you don’t specify this flag and the name can’t be found, <code>getnameinfo()</code> will put a string version of the IP address in <code>host</code> instead).</p>
|
|||
|
|
<p>As always, check your local man pages for the full scoop.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-7">Return Value</h3>
|
|||
|
|
<p>Returns zero on success, or non-zero on error. If the return value is non-zero, it can be passed to <code>gai_strerror()</code> to get a human-readable string. See <code>getaddrinfo</code> for more information.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-7">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb99"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb99-1"><a href="man-pages.html#cb99-1"></a><span class="kw">struct</span> sockaddr_in6 sa<span class="op">;</span> <span class="co">// could be IPv4 if you want</span></span>
|
|||
|
|
<span id="cb99-2"><a href="man-pages.html#cb99-2"></a><span class="dt">char</span> host<span class="op">[</span><span class="dv">1024</span><span class="op">];</span></span>
|
|||
|
|
<span id="cb99-3"><a href="man-pages.html#cb99-3"></a><span class="dt">char</span> service<span class="op">[</span><span class="dv">20</span><span class="op">];</span></span>
|
|||
|
|
<span id="cb99-4"><a href="man-pages.html#cb99-4"></a></span>
|
|||
|
|
<span id="cb99-5"><a href="man-pages.html#cb99-5"></a><span class="co">// pretend sa is full of good information about the host and port...</span></span>
|
|||
|
|
<span id="cb99-6"><a href="man-pages.html#cb99-6"></a></span>
|
|||
|
|
<span id="cb99-7"><a href="man-pages.html#cb99-7"></a>getnameinfo<span class="op">(&</span>sa<span class="op">,</span> <span class="kw">sizeof</span> sa<span class="op">,</span> host<span class="op">,</span> <span class="kw">sizeof</span> host<span class="op">,</span> service<span class="op">,</span> <span class="kw">sizeof</span> service<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb99-8"><a href="man-pages.html#cb99-8"></a></span>
|
|||
|
|
<span id="cb99-9"><a href="man-pages.html#cb99-9"></a>printf<span class="op">(</span><span class="st">" host: </span><span class="sc">%s\n</span><span class="st">"</span><span class="op">,</span> host<span class="op">);</span> <span class="co">// e.g. "www.example.com"</span></span>
|
|||
|
|
<span id="cb99-10"><a href="man-pages.html#cb99-10"></a>printf<span class="op">(</span><span class="st">"service: </span><span class="sc">%s\n</span><span class="st">"</span><span class="op">,</span> service<span class="op">);</span> <span class="co">// e.g. "http"</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-7">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#getaddrinfoman"><code>getaddrinfo()</code></a>, <a href="man-pages.html#gethostbynameman"><code>gethostbyaddr()</code></a></p>
|
|||
|
|
<h2 data-number="9.9" id="getpeernameman"><span class="header-section-number">9.9</span> <code>getpeername()</code></h2>
|
|||
|
|
<p></p>
|
|||
|
|
<p>Return address info about the remote side of the connection</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-8">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb100"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb100-1"><a href="man-pages.html#cb100-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb100-2"><a href="man-pages.html#cb100-2" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb100-3"><a href="man-pages.html#cb100-3" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> getpeername<span class="op">(</span><span class="dt">int</span> s<span class="op">,</span> <span class="kw">struct</span> sockaddr <span class="op">*</span>addr<span class="op">,</span> socklen_t <span class="op">*</span>len<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-8">Description</h3>
|
|||
|
|
<p>Once you have either <code>accept()</code>ed a remote connection, or <code>connect()</code>ed to a server, you now have what is known as a <em>peer</em>. Your peer is simply the computer you’re connected to, identified by an IP address and a port. So…</p>
|
|||
|
|
<p><code>getpeername()</code> simply returns a <code>struct sockaddr_in</code> filled with information about the machine you’re connected to.</p>
|
|||
|
|
<p>Why is it called a “name”? Well, there are a lot of different kinds of sockets, not just Internet Sockets like we’re using in this guide, and so “name” was a nice generic term that covered all cases. In our case, though, the peer’s “name” is it’s IP address and port.</p>
|
|||
|
|
<p>Although the function returns the size of the resultant address in <code>len</code>, you must preload <code>len</code> with the size of <code>addr</code>.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-8">Return Value</h3>
|
|||
|
|
<p>Returns zero on success, or <code>-1</code> on error (and <code>errno</code> will be set accordingly).</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-8">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb101"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb101-1"><a href="man-pages.html#cb101-1"></a><span class="co">// assume s is a connected socket</span></span>
|
|||
|
|
<span id="cb101-2"><a href="man-pages.html#cb101-2"></a></span>
|
|||
|
|
<span id="cb101-3"><a href="man-pages.html#cb101-3"></a>socklen_t len<span class="op">;</span></span>
|
|||
|
|
<span id="cb101-4"><a href="man-pages.html#cb101-4"></a><span class="kw">struct</span> sockaddr_storage addr<span class="op">;</span></span>
|
|||
|
|
<span id="cb101-5"><a href="man-pages.html#cb101-5"></a><span class="dt">char</span> ipstr<span class="op">[</span>INET6_ADDRSTRLEN<span class="op">];</span></span>
|
|||
|
|
<span id="cb101-6"><a href="man-pages.html#cb101-6"></a><span class="dt">int</span> port<span class="op">;</span></span>
|
|||
|
|
<span id="cb101-7"><a href="man-pages.html#cb101-7"></a></span>
|
|||
|
|
<span id="cb101-8"><a href="man-pages.html#cb101-8"></a>len <span class="op">=</span> <span class="kw">sizeof</span> addr<span class="op">;</span></span>
|
|||
|
|
<span id="cb101-9"><a href="man-pages.html#cb101-9"></a>getpeername<span class="op">(</span>s<span class="op">,</span> <span class="op">(</span><span class="kw">struct</span> sockaddr<span class="op">*)&</span>addr<span class="op">,</span> <span class="op">&</span>len<span class="op">);</span></span>
|
|||
|
|
<span id="cb101-10"><a href="man-pages.html#cb101-10"></a></span>
|
|||
|
|
<span id="cb101-11"><a href="man-pages.html#cb101-11"></a><span class="co">// deal with both IPv4 and IPv6:</span></span>
|
|||
|
|
<span id="cb101-12"><a href="man-pages.html#cb101-12"></a><span class="cf">if</span> <span class="op">(</span>addr<span class="op">.</span>ss_family <span class="op">==</span> AF_INET<span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb101-13"><a href="man-pages.html#cb101-13"></a> <span class="kw">struct</span> sockaddr_in <span class="op">*</span>s <span class="op">=</span> <span class="op">(</span><span class="kw">struct</span> sockaddr_in <span class="op">*)&</span>addr<span class="op">;</span></span>
|
|||
|
|
<span id="cb101-14"><a href="man-pages.html#cb101-14"></a> port <span class="op">=</span> ntohs<span class="op">(</span>s<span class="op">-></span>sin_port<span class="op">);</span></span>
|
|||
|
|
<span id="cb101-15"><a href="man-pages.html#cb101-15"></a> inet_ntop<span class="op">(</span>AF_INET<span class="op">,</span> <span class="op">&</span>s<span class="op">-></span>sin_addr<span class="op">,</span> ipstr<span class="op">,</span> <span class="kw">sizeof</span> ipstr<span class="op">);</span></span>
|
|||
|
|
<span id="cb101-16"><a href="man-pages.html#cb101-16"></a><span class="op">}</span> <span class="cf">else</span> <span class="op">{</span> <span class="co">// AF_INET6</span></span>
|
|||
|
|
<span id="cb101-17"><a href="man-pages.html#cb101-17"></a> <span class="kw">struct</span> sockaddr_in6 <span class="op">*</span>s <span class="op">=</span> <span class="op">(</span><span class="kw">struct</span> sockaddr_in6 <span class="op">*)&</span>addr<span class="op">;</span></span>
|
|||
|
|
<span id="cb101-18"><a href="man-pages.html#cb101-18"></a> port <span class="op">=</span> ntohs<span class="op">(</span>s<span class="op">-></span>sin6_port<span class="op">);</span></span>
|
|||
|
|
<span id="cb101-19"><a href="man-pages.html#cb101-19"></a> inet_ntop<span class="op">(</span>AF_INET6<span class="op">,</span> <span class="op">&</span>s<span class="op">-></span>sin6_addr<span class="op">,</span> ipstr<span class="op">,</span> <span class="kw">sizeof</span> ipstr<span class="op">);</span></span>
|
|||
|
|
<span id="cb101-20"><a href="man-pages.html#cb101-20"></a><span class="op">}</span></span>
|
|||
|
|
<span id="cb101-21"><a href="man-pages.html#cb101-21"></a></span>
|
|||
|
|
<span id="cb101-22"><a href="man-pages.html#cb101-22"></a>printf<span class="op">(</span><span class="st">"Peer IP address: </span><span class="sc">%s\n</span><span class="st">"</span><span class="op">,</span> ipstr<span class="op">);</span></span>
|
|||
|
|
<span id="cb101-23"><a href="man-pages.html#cb101-23"></a>printf<span class="op">(</span><span class="st">"Peer port : </span><span class="sc">%d\n</span><span class="st">"</span><span class="op">,</span> port<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-8">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#gethostnameman"><code>gethostname()</code></a>, <a href="man-pages.html#gethostbynameman"><code>gethostbyname()</code></a>, <a href="man-pages.html#gethostbynameman"><code>gethostbyaddr()</code></a></p>
|
|||
|
|
<h2 data-number="9.10" id="errnoman"><span class="header-section-number">9.10</span> <code>errno</code></h2>
|
|||
|
|
<p></p>
|
|||
|
|
<p>Holds the error code for the last system call</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-9">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb102"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb102-1"><a href="man-pages.html#cb102-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><errno.h></span></span>
|
|||
|
|
<span id="cb102-2"><a href="man-pages.html#cb102-2" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb102-3"><a href="man-pages.html#cb102-3" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> errno<span class="op">;</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-9">Description</h3>
|
|||
|
|
<p>This is the variable that holds error information for a lot of system calls. If you’ll recall, things like <code>socket()</code> and <code>listen()</code> return <code>-1</code> on error, and they set the exact value of <code>errno</code> to let you know specifically which error occurred.</p>
|
|||
|
|
<p>The header file <code>errno.h</code> lists a bunch of constant symbolic names for errors, such as <code>EADDRINUSE</code>, <code>EPIPE</code>, <code>ECONNREFUSED</code>, etc. Your local man pages will tell you what codes can be returned as an error, and you can use these at run time to handle different errors in different ways.</p>
|
|||
|
|
<p>Or, more commonly, you can call <code>perror()</code> or <code>strerror()</code> to get a human-readable version of the error.</p>
|
|||
|
|
<p>One thing to note, for you multithreading enthusiasts, is that on most systems <code>errno</code> is defined in a threadsafe manner. (That is, it’s not actually a global variable, but it behaves just like a global variable would in a single-threaded environment.)</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-9">Return Value</h3>
|
|||
|
|
<p>The value of the variable is the latest error to have transpired, which might be the code for “success” if the last action succeeded.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-9">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb103"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb103-1"><a href="man-pages.html#cb103-1"></a>s <span class="op">=</span> socket<span class="op">(</span>PF_INET<span class="op">,</span> SOCK_STREAM<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb103-2"><a href="man-pages.html#cb103-2"></a><span class="cf">if</span> <span class="op">(</span>s <span class="op">==</span> <span class="op">-</span><span class="dv">1</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb103-3"><a href="man-pages.html#cb103-3"></a> perror<span class="op">(</span><span class="st">"socket"</span><span class="op">);</span> <span class="co">// or use strerror()</span></span>
|
|||
|
|
<span id="cb103-4"><a href="man-pages.html#cb103-4"></a><span class="op">}</span></span>
|
|||
|
|
<span id="cb103-5"><a href="man-pages.html#cb103-5"></a></span>
|
|||
|
|
<span id="cb103-6"><a href="man-pages.html#cb103-6"></a>tryagain<span class="op">:</span></span>
|
|||
|
|
<span id="cb103-7"><a href="man-pages.html#cb103-7"></a><span class="cf">if</span> <span class="op">(</span>select<span class="op">(</span>n<span class="op">,</span> <span class="op">&</span>readfds<span class="op">,</span> NULL<span class="op">,</span> NULL<span class="op">)</span> <span class="op">==</span> <span class="op">-</span><span class="dv">1</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb103-8"><a href="man-pages.html#cb103-8"></a> <span class="co">// an error has occurred!!</span></span>
|
|||
|
|
<span id="cb103-9"><a href="man-pages.html#cb103-9"></a></span>
|
|||
|
|
<span id="cb103-10"><a href="man-pages.html#cb103-10"></a> <span class="co">// if we were only interrupted, just restart the select() call:</span></span>
|
|||
|
|
<span id="cb103-11"><a href="man-pages.html#cb103-11"></a> <span class="cf">if</span> <span class="op">(</span>errno <span class="op">==</span> EINTR<span class="op">)</span> <span class="cf">goto</span> tryagain<span class="op">;</span> <span class="co">// AAAA! goto!!!</span></span>
|
|||
|
|
<span id="cb103-12"><a href="man-pages.html#cb103-12"></a></span>
|
|||
|
|
<span id="cb103-13"><a href="man-pages.html#cb103-13"></a> <span class="co">// otherwise it's a more serious error:</span></span>
|
|||
|
|
<span id="cb103-14"><a href="man-pages.html#cb103-14"></a> perror<span class="op">(</span><span class="st">"select"</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb103-15"><a href="man-pages.html#cb103-15"></a> exit<span class="op">(</span><span class="dv">1</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb103-16"><a href="man-pages.html#cb103-16"></a><span class="op">}</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-9">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#perrorman"><code>perror()</code></a>, <a href="man-pages.html#perrorman"><code>strerror()</code></a></p>
|
|||
|
|
<h2 data-number="9.11" id="fcntlman"><span class="header-section-number">9.11</span> <code>fcntl()</code></h2>
|
|||
|
|
<p></p>
|
|||
|
|
<p>Control socket descriptors</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-10">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb104"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb104-1"><a href="man-pages.html#cb104-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/unistd.h></span></span>
|
|||
|
|
<span id="cb104-2"><a href="man-pages.html#cb104-2" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/fcntl.h></span></span>
|
|||
|
|
<span id="cb104-3"><a href="man-pages.html#cb104-3" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb104-4"><a href="man-pages.html#cb104-4" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> fcntl<span class="op">(</span><span class="dt">int</span> s<span class="op">,</span> <span class="dt">int</span> cmd<span class="op">,</span> <span class="dt">long</span> arg<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-10">Description</h3>
|
|||
|
|
<p>This function is typically used to do file locking and other file-oriented stuff, but it also has a couple socket-related functions that you might see or use from time to time.</p>
|
|||
|
|
<p>Parameter <code>s</code> is the socket descriptor you wish to operate on, <code>cmd</code> should be set to <code>F_SETFL</code>, and <code>arg</code> can be one of the following commands. (Like I said, there’s more to <code>fcntl()</code> than I’m letting on here, but I’m trying to stay socket-oriented.)</p>
|
|||
|
|
<table>
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 18%" />
|
|||
|
|
<col style="width: 81%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="header">
|
|||
|
|
<th><code>cmd</code></th>
|
|||
|
|
<th>Description</th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>O_NONBLOCK</code></td>
|
|||
|
|
<td>Set the socket to be non-blocking. See the section on <a href="slightly-advanced-techniques.html#blocking">blocking</a> for more details.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>O_ASYNC</code></td>
|
|||
|
|
<td>Set the socket to do asynchronous I/O. When data is ready to be <code>recv()</code>’d on the socket, the signal <code>SIGIO</code> will be raised. This is rare to see, and beyond the scope of the guide. And I think it’s only available on certain systems.</td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-10">Return Value</h3>
|
|||
|
|
<p>Returns zero on success, or <code>-1</code> on error (and <code>errno</code> will be set accordingly).</p>
|
|||
|
|
<p>Different uses of the <code>fcntl()</code> system call actually have different return values, but I haven’t covered them here because they’re not socket-related. See your local <code>fcntl()</code> man page for more information.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-10">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb105"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb105-1"><a href="man-pages.html#cb105-1"></a><span class="dt">int</span> s <span class="op">=</span> socket<span class="op">(</span>PF_INET<span class="op">,</span> SOCK_STREAM<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb105-2"><a href="man-pages.html#cb105-2"></a></span>
|
|||
|
|
<span id="cb105-3"><a href="man-pages.html#cb105-3"></a>fcntl<span class="op">(</span>s<span class="op">,</span> F_SETFL<span class="op">,</span> O_NONBLOCK<span class="op">);</span> <span class="co">// set to non-blocking</span></span>
|
|||
|
|
<span id="cb105-4"><a href="man-pages.html#cb105-4"></a>fcntl<span class="op">(</span>s<span class="op">,</span> F_SETFL<span class="op">,</span> O_ASYNC<span class="op">);</span> <span class="co">// set to asynchronous I/O</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-10">See Also</h3>
|
|||
|
|
<p><a href="slightly-advanced-techniques.html#blocking">Blocking</a>, <a href="man-pages.html#sendman"><code>send()</code></a></p>
|
|||
|
|
<h2 data-number="9.12" id="htonsman"><span class="header-section-number">9.12</span> <code>htons()</code>, <code>htonl()</code>, <code>ntohs()</code>, <code>ntohl()</code></h2>
|
|||
|
|
<p> </p>
|
|||
|
|
<p>Convert multi-byte integer types from host byte order to network byte order</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-11">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb106"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb106-1"><a href="man-pages.html#cb106-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><netinet/in.h></span></span>
|
|||
|
|
<span id="cb106-2"><a href="man-pages.html#cb106-2" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb106-3"><a href="man-pages.html#cb106-3" aria-hidden="true" tabindex="-1"></a><span class="dt">uint32_t</span> htonl<span class="op">(</span><span class="dt">uint32_t</span> hostlong<span class="op">);</span></span>
|
|||
|
|
<span id="cb106-4"><a href="man-pages.html#cb106-4" aria-hidden="true" tabindex="-1"></a><span class="dt">uint16_t</span> htons<span class="op">(</span><span class="dt">uint16_t</span> hostshort<span class="op">);</span></span>
|
|||
|
|
<span id="cb106-5"><a href="man-pages.html#cb106-5" aria-hidden="true" tabindex="-1"></a><span class="dt">uint32_t</span> ntohl<span class="op">(</span><span class="dt">uint32_t</span> netlong<span class="op">);</span></span>
|
|||
|
|
<span id="cb106-6"><a href="man-pages.html#cb106-6" aria-hidden="true" tabindex="-1"></a><span class="dt">uint16_t</span> ntohs<span class="op">(</span><span class="dt">uint16_t</span> netshort<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-11">Description</h3>
|
|||
|
|
<p>Just to make you really unhappy, different computers use different byte orderings internally for their multibyte integers (i.e. any integer that’s larger than a <code>char</code>). The upshot of this is that if you <code>send()</code> a two-byte <code>short int</code> from an Intel box to a Mac (before they became Intel boxes, too, I mean), what one computer thinks is the number <code>1</code>, the other will think is the number <code>256</code>, and vice-versa.</p>
|
|||
|
|
<p> The way to get around this problem is for everyone to put aside their differences and agree that Motorola and IBM had it right, and Intel did it the weird way, and so we all convert our byte orderings to “big-endian” before sending them out. Since Intel is a “little-endian” machine, it’s far more politically correct to call our preferred byte ordering “Network Byte Order”. So these functions convert from your native byte order to network byte order and back again.</p>
|
|||
|
|
<p>(This means on Intel these functions swap all the bytes around, and on PowerPC they do nothing because the bytes are already in Network Byte Order. But you should always use them in your code anyway, since someone might want to build it on an Intel machine and still have things work properly.)</p>
|
|||
|
|
<p>Note that the types involved are 32-bit (4 byte, probably <code>int</code>) and 16-bit (2 byte, very likely <code>short</code>) numbers. 64-bit machines might have a <code>htonll()</code> for 64-bit <code>int</code>s, but I’ve not seen it. You’ll just have to write your own.</p>
|
|||
|
|
<p>Anyway, the way these functions work is that you first decide if you’re converting <em>from</em> host (your machine’s) byte order or from network byte order. If “host”, the the first letter of the function you’re going to call is “h”. Otherwise it’s “n” for “network”. The middle of the function name is always “to” because you’re converting from one “to” another, and the penultimate letter shows what you’re converting <em>to</em>. The last letter is the size of the data, “s” for short, or “l” for long. Thus:</p>
|
|||
|
|
<table>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="header">
|
|||
|
|
<th>Function</th>
|
|||
|
|
<th>Description</th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>htons()</code></td>
|
|||
|
|
<td><code>h</code>ost <code>to</code> <code>n</code>etwork <code>s</code>hort</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>htonl()</code></td>
|
|||
|
|
<td><code>h</code>ost <code>to</code> <code>n</code>etwork <code>l</code>ong</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>ntohs()</code></td>
|
|||
|
|
<td><code>n</code>etwork <code>to</code> <code>h</code>ost <code>s</code>hort</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>ntohl()</code></td>
|
|||
|
|
<td><code>n</code>etwork <code>to</code> <code>h</code>ost <code>l</code>ong</td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-11">Return Value</h3>
|
|||
|
|
<p>Each function returns the converted value.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-11">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb107"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb107-1"><a href="man-pages.html#cb107-1"></a><span class="dt">uint32_t</span> some_long <span class="op">=</span> <span class="dv">10</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb107-2"><a href="man-pages.html#cb107-2"></a><span class="dt">uint16_t</span> some_short <span class="op">=</span> <span class="dv">20</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb107-3"><a href="man-pages.html#cb107-3"></a></span>
|
|||
|
|
<span id="cb107-4"><a href="man-pages.html#cb107-4"></a><span class="dt">uint32_t</span> network_byte_order<span class="op">;</span></span>
|
|||
|
|
<span id="cb107-5"><a href="man-pages.html#cb107-5"></a></span>
|
|||
|
|
<span id="cb107-6"><a href="man-pages.html#cb107-6"></a><span class="co">// convert and send</span></span>
|
|||
|
|
<span id="cb107-7"><a href="man-pages.html#cb107-7"></a>network_byte_order <span class="op">=</span> htonl<span class="op">(</span>some_long<span class="op">);</span></span>
|
|||
|
|
<span id="cb107-8"><a href="man-pages.html#cb107-8"></a>send<span class="op">(</span>s<span class="op">,</span> <span class="op">&</span>network_byte_order<span class="op">,</span> <span class="kw">sizeof</span><span class="op">(</span><span class="dt">uint32_t</span><span class="op">),</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb107-9"><a href="man-pages.html#cb107-9"></a></span>
|
|||
|
|
<span id="cb107-10"><a href="man-pages.html#cb107-10"></a>some_short <span class="op">==</span> ntohs<span class="op">(</span>htons<span class="op">(</span>some_short<span class="op">));</span> <span class="co">// this expression is true</span></span></code></pre></div>
|
|||
|
|
<h2 data-number="9.13" id="inet_ntoaman"><span class="header-section-number">9.13</span> <code>inet_ntoa()</code>, <code>inet_aton()</code>, <code>inet_addr</code></h2>
|
|||
|
|
<p> </p>
|
|||
|
|
<p>Convert IP addresses from a dots-and-number string to a <code>struct in_addr</code> and back</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-12">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb108"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb108-1"><a href="man-pages.html#cb108-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb108-2"><a href="man-pages.html#cb108-2" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><netinet/in.h></span></span>
|
|||
|
|
<span id="cb108-3"><a href="man-pages.html#cb108-3" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><arpa/inet.h></span></span>
|
|||
|
|
<span id="cb108-4"><a href="man-pages.html#cb108-4" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb108-5"><a href="man-pages.html#cb108-5" aria-hidden="true" tabindex="-1"></a><span class="co">// ALL THESE ARE </span><span class="al">DEPRECATED</span><span class="co">! Use inet_pton() or inet_ntop() instead!!</span></span>
|
|||
|
|
<span id="cb108-6"><a href="man-pages.html#cb108-6" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb108-7"><a href="man-pages.html#cb108-7" aria-hidden="true" tabindex="-1"></a><span class="dt">char</span> <span class="op">*</span>inet_ntoa<span class="op">(</span><span class="kw">struct</span> in_addr in<span class="op">);</span></span>
|
|||
|
|
<span id="cb108-8"><a href="man-pages.html#cb108-8" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> inet_aton<span class="op">(</span><span class="dt">const</span> <span class="dt">char</span> <span class="op">*</span>cp<span class="op">,</span> <span class="kw">struct</span> in_addr <span class="op">*</span>inp<span class="op">);</span></span>
|
|||
|
|
<span id="cb108-9"><a href="man-pages.html#cb108-9" aria-hidden="true" tabindex="-1"></a>in_addr_t inet_addr<span class="op">(</span><span class="dt">const</span> <span class="dt">char</span> <span class="op">*</span>cp<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-12">Description</h3>
|
|||
|
|
<p><em>These functions are deprecated because they don’t handle IPv6! Use (<code>inet_ntop()</code>)[#inet_ntopman] or (<code>inet_pton()</code>)[#inet_ntopman] instead! They are included here because they can still be found in the wild.</em></p>
|
|||
|
|
<p>All of these functions convert from a <code>struct in_addr</code> (part of your <code>struct sockaddr_in</code>, most likely) to a string in dots-and-numbers format (e.g. “192.168.5.10”) and vice-versa. If you have an IP address passed on the command line or something, this is the easiest way to get a <code>struct in_addr</code> to <code>connect()</code> to, or whatever. If you need more power, try some of the DNS functions like <code>gethostbyname()</code> or attempt a <em>coup d’État</em> in your local country.</p>
|
|||
|
|
<p>The function <code>inet_ntoa()</code> converts a network address in a <code>struct in_addr</code> to a dots-and-numbers format string. The “n” in “ntoa” stands for network, and the “a” stands for ASCII for historical reasons (so it’s “Network To ASCII”—the “toa” suffix has an analogous friend in the C library called <code>atoi()</code> which converts an ASCII string to an integer).</p>
|
|||
|
|
<p>The function <code>inet_aton()</code> is the opposite, converting from a dots-and-numbers string into a <code>in_addr_t</code> (which is the type of the field <code>s_addr</code> in your <code>struct in_addr</code>).</p>
|
|||
|
|
<p>Finally, the function <code>inet_addr()</code> is an older function that does basically the same thing as <code>inet_aton()</code>. It’s theoretically deprecated, but you’ll see it a lot and the police won’t come get you if you use it.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-12">Return Value</h3>
|
|||
|
|
<p><code>inet_aton()</code> returns non-zero if the address is a valid one, and it returns zero if the address is invalid.</p>
|
|||
|
|
<p><code>inet_ntoa()</code> returns the dots-and-numbers string in a static buffer that is overwritten with each call to the function.</p>
|
|||
|
|
<p><code>inet_addr()</code> returns the address as an <code>in_addr_t</code>, or <code>-1</code> if there’s an error. (That is the same result as if you tried to convert the string “<code>255.255.255.255</code>”, which is a valid IP address. This is why <code>inet_aton()</code> is better.)</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-12">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb109"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb109-1"><a href="man-pages.html#cb109-1"></a><span class="kw">struct</span> sockaddr_in antelope<span class="op">;</span></span>
|
|||
|
|
<span id="cb109-2"><a href="man-pages.html#cb109-2"></a><span class="dt">char</span> <span class="op">*</span>some_addr<span class="op">;</span></span>
|
|||
|
|
<span id="cb109-3"><a href="man-pages.html#cb109-3"></a></span>
|
|||
|
|
<span id="cb109-4"><a href="man-pages.html#cb109-4"></a>inet_aton<span class="op">(</span><span class="st">"10.0.0.1"</span><span class="op">,</span> <span class="op">&</span>antelope<span class="op">.</span>sin_addr<span class="op">);</span> <span class="co">// store IP in antelope</span></span>
|
|||
|
|
<span id="cb109-5"><a href="man-pages.html#cb109-5"></a></span>
|
|||
|
|
<span id="cb109-6"><a href="man-pages.html#cb109-6"></a>some_addr <span class="op">=</span> inet_ntoa<span class="op">(</span>antelope<span class="op">.</span>sin_addr<span class="op">);</span> <span class="co">// return the IP</span></span>
|
|||
|
|
<span id="cb109-7"><a href="man-pages.html#cb109-7"></a>printf<span class="op">(</span><span class="st">"</span><span class="sc">%s\n</span><span class="st">"</span><span class="op">,</span> some_addr<span class="op">);</span> <span class="co">// prints "10.0.0.1"</span></span>
|
|||
|
|
<span id="cb109-8"><a href="man-pages.html#cb109-8"></a></span>
|
|||
|
|
<span id="cb109-9"><a href="man-pages.html#cb109-9"></a><span class="co">// and this call is the same as the inet_aton() call, above:</span></span>
|
|||
|
|
<span id="cb109-10"><a href="man-pages.html#cb109-10"></a>antelope<span class="op">.</span>sin_addr<span class="op">.</span>s_addr <span class="op">=</span> inet_addr<span class="op">(</span><span class="st">"10.0.0.1"</span><span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-11">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#inet_ntopman"><code>inet_ntop()</code></a>, <a href="man-pages.html#inet_ntopman"><code>inet_pton()</code></a>, <a href="man-pages.html#gethostbynameman"><code>gethostbyname()</code></a>, <a href="man-pages.html#gethostbynameman"><code>gethostbyaddr()</code></a></p>
|
|||
|
|
<h2 data-number="9.14" id="inet_ntopman"><span class="header-section-number">9.14</span> <code>inet_ntop()</code>, <code>inet_pton()</code></h2>
|
|||
|
|
<p> </p>
|
|||
|
|
<p>Convert IP addresses to human-readable form and back.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-13">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb110"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb110-1"><a href="man-pages.html#cb110-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><arpa/inet.h></span></span>
|
|||
|
|
<span id="cb110-2"><a href="man-pages.html#cb110-2" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb110-3"><a href="man-pages.html#cb110-3" aria-hidden="true" tabindex="-1"></a><span class="dt">const</span> <span class="dt">char</span> <span class="op">*</span>inet_ntop<span class="op">(</span><span class="dt">int</span> af<span class="op">,</span> <span class="dt">const</span> <span class="dt">void</span> <span class="op">*</span>src<span class="op">,</span></span>
|
|||
|
|
<span id="cb110-4"><a href="man-pages.html#cb110-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">char</span> <span class="op">*</span>dst<span class="op">,</span> socklen_t size<span class="op">);</span></span>
|
|||
|
|
<span id="cb110-5"><a href="man-pages.html#cb110-5" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb110-6"><a href="man-pages.html#cb110-6" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> inet_pton<span class="op">(</span><span class="dt">int</span> af<span class="op">,</span> <span class="dt">const</span> <span class="dt">char</span> <span class="op">*</span>src<span class="op">,</span> <span class="dt">void</span> <span class="op">*</span>dst<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-13">Description</h3>
|
|||
|
|
<p>These functions are for dealing with human-readable IP addresses and converting them to their binary representation for use with various functions and system calls. The “n” stands for “network”, and “p” for “presentation”. Or “text presentation”. But you can think of it as “printable”. “ntop” is “network to printable”. See?</p>
|
|||
|
|
<p>Sometimes you don’t want to look at a pile of binary numbers when looking at an IP address. You want it in a nice printable form, like <code>192.0.2.180</code>, or <code>2001:db8:8714:3a90::12</code>. In that case, <code>inet_ntop()</code> is for you.</p>
|
|||
|
|
<p><code>inet_ntop()</code> takes the address family in the <code>af</code> parameter (either <code>AF_INET</code> or <code>AF_INET6</code>). The <code>src</code> parameter should be a pointer to either a <code>struct in_addr</code> or <code>struct in6_addr</code> containing the address you wish to convert to a string. Finally <code>dst</code> and <code>size</code> are the pointer to the destination string and the maximum length of that string.</p>
|
|||
|
|
<p>What should the maximum length of the <code>dst</code> string be? What is the maximum length for IPv4 and IPv6 addresses? Fortunately there are a couple of macros to help you out. The maximum lengths are: <code>INET_ADDRSTRLEN</code> and <code>INET6_ADDRSTRLEN</code>.</p>
|
|||
|
|
<p>Other times, you might have a string containing an IP address in readable form, and you want to pack it into a <code>struct sockaddr_in</code> or a <code>struct sockaddr_in6</code>. In that case, the opposite function <code>inet_pton()</code> is what you’re after.</p>
|
|||
|
|
<p><code>inet_pton()</code> also takes an address family (either <code>AF_INET</code> or <code>AF_INET6</code>) in the <code>af</code> parameter. The <code>src</code> parameter is a pointer to a string containing the IP address in printable form. Lastly the <code>dst</code> parameter points to where the result should be stored, which is probably a <code>struct in_addr</code> or <code>struct in6_addr</code>.</p>
|
|||
|
|
<p>These functions don’t do DNS lookups—you’ll need <code>getaddrinfo()</code> for that.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-13">Return Value</h3>
|
|||
|
|
<p><code>inet_ntop()</code> returns the <code>dst</code> parameter on success, or <code>NULL</code> on failure (and <code>errno</code> is set).</p>
|
|||
|
|
<p><code>inet_pton()</code> returns <code>1</code> on success. It returns <code>-1</code> if there was an error (<code>errno</code> is set), or <code>0</code> if the input isn’t a valid IP address.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-13">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb111"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb111-1"><a href="man-pages.html#cb111-1"></a><span class="co">// IPv4 demo of inet_ntop() and inet_pton()</span></span>
|
|||
|
|
<span id="cb111-2"><a href="man-pages.html#cb111-2"></a></span>
|
|||
|
|
<span id="cb111-3"><a href="man-pages.html#cb111-3"></a><span class="kw">struct</span> sockaddr_in sa<span class="op">;</span></span>
|
|||
|
|
<span id="cb111-4"><a href="man-pages.html#cb111-4"></a><span class="dt">char</span> str<span class="op">[</span>INET_ADDRSTRLEN<span class="op">];</span></span>
|
|||
|
|
<span id="cb111-5"><a href="man-pages.html#cb111-5"></a></span>
|
|||
|
|
<span id="cb111-6"><a href="man-pages.html#cb111-6"></a><span class="co">// store this IP address in sa:</span></span>
|
|||
|
|
<span id="cb111-7"><a href="man-pages.html#cb111-7"></a>inet_pton<span class="op">(</span>AF_INET<span class="op">,</span> <span class="st">"192.0.2.33"</span><span class="op">,</span> <span class="op">&(</span>sa<span class="op">.</span>sin_addr<span class="op">));</span></span>
|
|||
|
|
<span id="cb111-8"><a href="man-pages.html#cb111-8"></a></span>
|
|||
|
|
<span id="cb111-9"><a href="man-pages.html#cb111-9"></a><span class="co">// now get it back and print it</span></span>
|
|||
|
|
<span id="cb111-10"><a href="man-pages.html#cb111-10"></a>inet_ntop<span class="op">(</span>AF_INET<span class="op">,</span> <span class="op">&(</span>sa<span class="op">.</span>sin_addr<span class="op">),</span> str<span class="op">,</span> INET_ADDRSTRLEN<span class="op">);</span></span>
|
|||
|
|
<span id="cb111-11"><a href="man-pages.html#cb111-11"></a></span>
|
|||
|
|
<span id="cb111-12"><a href="man-pages.html#cb111-12"></a>printf<span class="op">(</span><span class="st">"</span><span class="sc">%s\n</span><span class="st">"</span><span class="op">,</span> str<span class="op">);</span> <span class="co">// prints "192.0.2.33"</span></span></code></pre></div>
|
|||
|
|
<div class="sourceCode" id="cb112"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb112-1"><a href="man-pages.html#cb112-1"></a><span class="co">// IPv6 demo of inet_ntop() and inet_pton()</span></span>
|
|||
|
|
<span id="cb112-2"><a href="man-pages.html#cb112-2"></a><span class="co">// (basically the same except with a bunch of 6s thrown around)</span></span>
|
|||
|
|
<span id="cb112-3"><a href="man-pages.html#cb112-3"></a></span>
|
|||
|
|
<span id="cb112-4"><a href="man-pages.html#cb112-4"></a><span class="kw">struct</span> sockaddr_in6 sa<span class="op">;</span></span>
|
|||
|
|
<span id="cb112-5"><a href="man-pages.html#cb112-5"></a><span class="dt">char</span> str<span class="op">[</span>INET6_ADDRSTRLEN<span class="op">];</span></span>
|
|||
|
|
<span id="cb112-6"><a href="man-pages.html#cb112-6"></a></span>
|
|||
|
|
<span id="cb112-7"><a href="man-pages.html#cb112-7"></a><span class="co">// store this IP address in sa:</span></span>
|
|||
|
|
<span id="cb112-8"><a href="man-pages.html#cb112-8"></a>inet_pton<span class="op">(</span>AF_INET6<span class="op">,</span> <span class="st">"2001:db8:8714:3a90::12"</span><span class="op">,</span> <span class="op">&(</span>sa<span class="op">.</span>sin6_addr<span class="op">));</span></span>
|
|||
|
|
<span id="cb112-9"><a href="man-pages.html#cb112-9"></a></span>
|
|||
|
|
<span id="cb112-10"><a href="man-pages.html#cb112-10"></a><span class="co">// now get it back and print it</span></span>
|
|||
|
|
<span id="cb112-11"><a href="man-pages.html#cb112-11"></a>inet_ntop<span class="op">(</span>AF_INET6<span class="op">,</span> <span class="op">&(</span>sa<span class="op">.</span>sin6_addr<span class="op">),</span> str<span class="op">,</span> INET6_ADDRSTRLEN<span class="op">);</span></span>
|
|||
|
|
<span id="cb112-12"><a href="man-pages.html#cb112-12"></a></span>
|
|||
|
|
<span id="cb112-13"><a href="man-pages.html#cb112-13"></a>printf<span class="op">(</span><span class="st">"</span><span class="sc">%s\n</span><span class="st">"</span><span class="op">,</span> str<span class="op">);</span> <span class="co">// prints "2001:db8:8714:3a90::12"</span></span></code></pre></div>
|
|||
|
|
<div class="sourceCode" id="cb113"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb113-1"><a href="man-pages.html#cb113-1"></a><span class="co">// Helper function you can use:</span></span>
|
|||
|
|
<span id="cb113-2"><a href="man-pages.html#cb113-2"></a></span>
|
|||
|
|
<span id="cb113-3"><a href="man-pages.html#cb113-3"></a><span class="co">//Convert a struct sockaddr address to a string, IPv4 and IPv6:</span></span>
|
|||
|
|
<span id="cb113-4"><a href="man-pages.html#cb113-4"></a></span>
|
|||
|
|
<span id="cb113-5"><a href="man-pages.html#cb113-5"></a><span class="dt">char</span> <span class="op">*</span>get_ip_str<span class="op">(</span><span class="dt">const</span> <span class="kw">struct</span> sockaddr <span class="op">*</span>sa<span class="op">,</span> <span class="dt">char</span> <span class="op">*</span>s<span class="op">,</span> <span class="dt">size_t</span> maxlen<span class="op">)</span></span>
|
|||
|
|
<span id="cb113-6"><a href="man-pages.html#cb113-6"></a><span class="op">{</span></span>
|
|||
|
|
<span id="cb113-7"><a href="man-pages.html#cb113-7"></a> <span class="cf">switch</span><span class="op">(</span>sa<span class="op">-></span>sa_family<span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb113-8"><a href="man-pages.html#cb113-8"></a> <span class="cf">case</span> AF_INET<span class="op">:</span></span>
|
|||
|
|
<span id="cb113-9"><a href="man-pages.html#cb113-9"></a> inet_ntop<span class="op">(</span>AF_INET<span class="op">,</span> <span class="op">&(((</span><span class="kw">struct</span> sockaddr_in <span class="op">*)</span>sa<span class="op">)-></span>sin_addr<span class="op">),</span></span>
|
|||
|
|
<span id="cb113-10"><a href="man-pages.html#cb113-10"></a> s<span class="op">,</span> maxlen<span class="op">);</span></span>
|
|||
|
|
<span id="cb113-11"><a href="man-pages.html#cb113-11"></a> <span class="cf">break</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb113-12"><a href="man-pages.html#cb113-12"></a></span>
|
|||
|
|
<span id="cb113-13"><a href="man-pages.html#cb113-13"></a> <span class="cf">case</span> AF_INET6<span class="op">:</span></span>
|
|||
|
|
<span id="cb113-14"><a href="man-pages.html#cb113-14"></a> inet_ntop<span class="op">(</span>AF_INET6<span class="op">,</span> <span class="op">&(((</span><span class="kw">struct</span> sockaddr_in6 <span class="op">*)</span>sa<span class="op">)-></span>sin6_addr<span class="op">),</span></span>
|
|||
|
|
<span id="cb113-15"><a href="man-pages.html#cb113-15"></a> s<span class="op">,</span> maxlen<span class="op">);</span></span>
|
|||
|
|
<span id="cb113-16"><a href="man-pages.html#cb113-16"></a> <span class="cf">break</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb113-17"><a href="man-pages.html#cb113-17"></a></span>
|
|||
|
|
<span id="cb113-18"><a href="man-pages.html#cb113-18"></a> <span class="cf">default</span><span class="op">:</span></span>
|
|||
|
|
<span id="cb113-19"><a href="man-pages.html#cb113-19"></a> strncpy<span class="op">(</span>s<span class="op">,</span> <span class="st">"Unknown AF"</span><span class="op">,</span> maxlen<span class="op">);</span></span>
|
|||
|
|
<span id="cb113-20"><a href="man-pages.html#cb113-20"></a> <span class="cf">return</span> NULL<span class="op">;</span></span>
|
|||
|
|
<span id="cb113-21"><a href="man-pages.html#cb113-21"></a> <span class="op">}</span></span>
|
|||
|
|
<span id="cb113-22"><a href="man-pages.html#cb113-22"></a></span>
|
|||
|
|
<span id="cb113-23"><a href="man-pages.html#cb113-23"></a> <span class="cf">return</span> s<span class="op">;</span></span>
|
|||
|
|
<span id="cb113-24"><a href="man-pages.html#cb113-24"></a><span class="op">}</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-12">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#getaddrinfoman"><code>getaddrinfo()</code></a></p>
|
|||
|
|
<h2 data-number="9.15" id="listenman"><span class="header-section-number">9.15</span> <code>listen()</code></h2>
|
|||
|
|
<p></p>
|
|||
|
|
<p>Tell a socket to listen for incoming connections</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-14">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb114"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb114-1"><a href="man-pages.html#cb114-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb114-2"><a href="man-pages.html#cb114-2" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb114-3"><a href="man-pages.html#cb114-3" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> listen<span class="op">(</span><span class="dt">int</span> s<span class="op">,</span> <span class="dt">int</span> backlog<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-14">Description</h3>
|
|||
|
|
<p>You can take your socket descriptor (made with the <code>socket()</code> system call) and tell it to listen for incoming connections. This is what differentiates the servers from the clients, guys.</p>
|
|||
|
|
<p>The <code>backlog</code> parameter can mean a couple different things depending on the system you on, but loosely it is how many pending connections you can have before the kernel starts rejecting new ones. So as the new connections come in, you should be quick to <code>accept()</code> them so that the backlog doesn’t fill. Try setting it to 10 or so, and if your clients start getting “Connection refused” under heavy load, set it higher.</p>
|
|||
|
|
<p>Before calling <code>listen()</code>, your server should call <code>bind()</code> to attach itself to a specific port number. That port number (on the server’s IP address) will be the one that clients connect to.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-14">Return Value</h3>
|
|||
|
|
<p>Returns zero on success, or <code>-1</code> on error (and <code>errno</code> will be set accordingly).</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-14">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb115"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb115-1"><a href="man-pages.html#cb115-1"></a><span class="kw">struct</span> addrinfo hints<span class="op">,</span> <span class="op">*</span>res<span class="op">;</span></span>
|
|||
|
|
<span id="cb115-2"><a href="man-pages.html#cb115-2"></a><span class="dt">int</span> sockfd<span class="op">;</span></span>
|
|||
|
|
<span id="cb115-3"><a href="man-pages.html#cb115-3"></a></span>
|
|||
|
|
<span id="cb115-4"><a href="man-pages.html#cb115-4"></a><span class="co">// first, load up address structs with getaddrinfo():</span></span>
|
|||
|
|
<span id="cb115-5"><a href="man-pages.html#cb115-5"></a></span>
|
|||
|
|
<span id="cb115-6"><a href="man-pages.html#cb115-6"></a>memset<span class="op">(&</span>hints<span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="kw">sizeof</span> hints<span class="op">);</span></span>
|
|||
|
|
<span id="cb115-7"><a href="man-pages.html#cb115-7"></a>hints<span class="op">.</span>ai_family <span class="op">=</span> AF_UNSPEC<span class="op">;</span> <span class="co">// use IPv4 or IPv6, whichever</span></span>
|
|||
|
|
<span id="cb115-8"><a href="man-pages.html#cb115-8"></a>hints<span class="op">.</span>ai_socktype <span class="op">=</span> SOCK_STREAM<span class="op">;</span></span>
|
|||
|
|
<span id="cb115-9"><a href="man-pages.html#cb115-9"></a>hints<span class="op">.</span>ai_flags <span class="op">=</span> AI_PASSIVE<span class="op">;</span> <span class="co">// fill in my IP for me</span></span>
|
|||
|
|
<span id="cb115-10"><a href="man-pages.html#cb115-10"></a></span>
|
|||
|
|
<span id="cb115-11"><a href="man-pages.html#cb115-11"></a>getaddrinfo<span class="op">(</span>NULL<span class="op">,</span> <span class="st">"3490"</span><span class="op">,</span> <span class="op">&</span>hints<span class="op">,</span> <span class="op">&</span>res<span class="op">);</span></span>
|
|||
|
|
<span id="cb115-12"><a href="man-pages.html#cb115-12"></a></span>
|
|||
|
|
<span id="cb115-13"><a href="man-pages.html#cb115-13"></a><span class="co">// make a socket:</span></span>
|
|||
|
|
<span id="cb115-14"><a href="man-pages.html#cb115-14"></a></span>
|
|||
|
|
<span id="cb115-15"><a href="man-pages.html#cb115-15"></a>sockfd <span class="op">=</span> socket<span class="op">(</span>res<span class="op">-></span>ai_family<span class="op">,</span> res<span class="op">-></span>ai_socktype<span class="op">,</span> res<span class="op">-></span>ai_protocol<span class="op">);</span></span>
|
|||
|
|
<span id="cb115-16"><a href="man-pages.html#cb115-16"></a></span>
|
|||
|
|
<span id="cb115-17"><a href="man-pages.html#cb115-17"></a><span class="co">// bind it to the port we passed in to getaddrinfo():</span></span>
|
|||
|
|
<span id="cb115-18"><a href="man-pages.html#cb115-18"></a></span>
|
|||
|
|
<span id="cb115-19"><a href="man-pages.html#cb115-19"></a>bind<span class="op">(</span>sockfd<span class="op">,</span> res<span class="op">-></span>ai_addr<span class="op">,</span> res<span class="op">-></span>ai_addrlen<span class="op">);</span></span>
|
|||
|
|
<span id="cb115-20"><a href="man-pages.html#cb115-20"></a></span>
|
|||
|
|
<span id="cb115-21"><a href="man-pages.html#cb115-21"></a>listen<span class="op">(</span>sockfd<span class="op">,</span> <span class="dv">10</span><span class="op">);</span> <span class="co">// set s up to be a server (listening) socket</span></span>
|
|||
|
|
<span id="cb115-22"><a href="man-pages.html#cb115-22"></a></span>
|
|||
|
|
<span id="cb115-23"><a href="man-pages.html#cb115-23"></a><span class="co">// then have an accept() loop down here somewhere</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-13">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#acceptman"><code>accept()</code></a>, <a href="man-pages.html#bindman"><code>bind()</code></a>, <a href="man-pages.html#socketman"><code>socket()</code></a></p>
|
|||
|
|
<h2 data-number="9.16" id="perrorman"><span class="header-section-number">9.16</span> <code>perror()</code>, <code>strerror()</code></h2>
|
|||
|
|
<p> </p>
|
|||
|
|
<p>Print an error as a human-readable string</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-15">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb116"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb116-1"><a href="man-pages.html#cb116-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><stdio.h></span></span>
|
|||
|
|
<span id="cb116-2"><a href="man-pages.html#cb116-2" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><string.h></span><span class="pp"> </span><span class="co">// for strerror()</span></span>
|
|||
|
|
<span id="cb116-3"><a href="man-pages.html#cb116-3" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb116-4"><a href="man-pages.html#cb116-4" aria-hidden="true" tabindex="-1"></a><span class="dt">void</span> perror<span class="op">(</span><span class="dt">const</span> <span class="dt">char</span> <span class="op">*</span>s<span class="op">);</span></span>
|
|||
|
|
<span id="cb116-5"><a href="man-pages.html#cb116-5" aria-hidden="true" tabindex="-1"></a><span class="dt">char</span> <span class="op">*</span>strerror<span class="op">(</span><span class="dt">int</span> errnum<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-15">Description</h3>
|
|||
|
|
<p>Since so many functions return <code>-1</code> on error and set the value of the variable <code>errno</code> to be some number, it would sure be nice if you could easily print that in a form that made sense to you.</p>
|
|||
|
|
<p>Mercifully, <code>perror()</code> does that. If you want more description to be printed before the error, you can point the parameter <code>s</code> to it (or you can leave <code>s</code> as <code>NULL</code> and nothing additional will be printed).</p>
|
|||
|
|
<p>In a nutshell, this function takes <code>errno</code> values, like <code>ECONNRESET</code>, and prints them nicely, like “Connection reset by peer.”</p>
|
|||
|
|
<p>The function <code>strerror()</code> is very similar to <code>perror()</code>, except it returns a pointer to the error message string for a given value (you usually pass in the variable <code>errno</code>).</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-15">Return Value</h3>
|
|||
|
|
<p><code>strerror()</code> returns a pointer to the error message string.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-15">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb117"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb117-1"><a href="man-pages.html#cb117-1"></a><span class="dt">int</span> s<span class="op">;</span></span>
|
|||
|
|
<span id="cb117-2"><a href="man-pages.html#cb117-2"></a></span>
|
|||
|
|
<span id="cb117-3"><a href="man-pages.html#cb117-3"></a>s <span class="op">=</span> socket<span class="op">(</span>PF_INET<span class="op">,</span> SOCK_STREAM<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb117-4"><a href="man-pages.html#cb117-4"></a></span>
|
|||
|
|
<span id="cb117-5"><a href="man-pages.html#cb117-5"></a><span class="cf">if</span> <span class="op">(</span>s <span class="op">==</span> <span class="op">-</span><span class="dv">1</span><span class="op">)</span> <span class="op">{</span> <span class="co">// some error has occurred</span></span>
|
|||
|
|
<span id="cb117-6"><a href="man-pages.html#cb117-6"></a> <span class="co">// prints "socket error: " + the error message:</span></span>
|
|||
|
|
<span id="cb117-7"><a href="man-pages.html#cb117-7"></a> perror<span class="op">(</span><span class="st">"socket error"</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb117-8"><a href="man-pages.html#cb117-8"></a><span class="op">}</span></span>
|
|||
|
|
<span id="cb117-9"><a href="man-pages.html#cb117-9"></a></span>
|
|||
|
|
<span id="cb117-10"><a href="man-pages.html#cb117-10"></a><span class="co">// similarly:</span></span>
|
|||
|
|
<span id="cb117-11"><a href="man-pages.html#cb117-11"></a><span class="cf">if</span> <span class="op">(</span>listen<span class="op">(</span>s<span class="op">,</span> <span class="dv">10</span><span class="op">)</span> <span class="op">==</span> <span class="op">-</span><span class="dv">1</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb117-12"><a href="man-pages.html#cb117-12"></a> <span class="co">// this prints "an error: " + the error message from errno:</span></span>
|
|||
|
|
<span id="cb117-13"><a href="man-pages.html#cb117-13"></a> printf<span class="op">(</span><span class="st">"an error: </span><span class="sc">%s\n</span><span class="st">"</span><span class="op">,</span> strerror<span class="op">(</span>errno<span class="op">));</span></span>
|
|||
|
|
<span id="cb117-14"><a href="man-pages.html#cb117-14"></a><span class="op">}</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-14">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#errnoman"><code>errno</code></a></p>
|
|||
|
|
<h2 data-number="9.17" id="pollman"><span class="header-section-number">9.17</span> <code>poll()</code></h2>
|
|||
|
|
<p></p>
|
|||
|
|
<p>Test for events on multiple sockets simultaneously</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-16">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb118"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb118-1"><a href="man-pages.html#cb118-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/poll.h></span></span>
|
|||
|
|
<span id="cb118-2"><a href="man-pages.html#cb118-2" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb118-3"><a href="man-pages.html#cb118-3" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> poll<span class="op">(</span><span class="kw">struct</span> pollfd <span class="op">*</span>ufds<span class="op">,</span> <span class="dt">unsigned</span> <span class="dt">int</span> nfds<span class="op">,</span> <span class="dt">int</span> timeout<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-16">Description</h3>
|
|||
|
|
<p>This function is very similar to <code>select()</code> in that they both watch sets of file descriptors for events, such as incoming data ready to <code>recv()</code>, socket ready to <code>send()</code> data to, out-of-band data ready to <code>recv()</code>, errors, etc.</p>
|
|||
|
|
<p>The basic idea is that you pass an array of <code>nfds</code> <code>struct pollfd</code>s in <code>ufds</code>, along with a timeout in milliseconds (1000 milliseconds in a second). The <code>timeout</code> can be negative if you want to wait forever. If no event happens on any of the socket descriptors by the timeout, <code>poll()</code> will return.</p>
|
|||
|
|
<p>Each element in the array of <code>struct pollfd</code>s represents one socket descriptor, and contains the following fields:</p>
|
|||
|
|
<p></p>
|
|||
|
|
<div class="sourceCode" id="cb119"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb119-1"><a href="man-pages.html#cb119-1" aria-hidden="true" tabindex="-1"></a><span class="kw">struct</span> pollfd <span class="op">{</span></span>
|
|||
|
|
<span id="cb119-2"><a href="man-pages.html#cb119-2" aria-hidden="true" tabindex="-1"></a> <span class="dt">int</span> fd<span class="op">;</span> <span class="co">// the socket descriptor</span></span>
|
|||
|
|
<span id="cb119-3"><a href="man-pages.html#cb119-3" aria-hidden="true" tabindex="-1"></a> <span class="dt">short</span> events<span class="op">;</span> <span class="co">// bitmap of events we're interested in</span></span>
|
|||
|
|
<span id="cb119-4"><a href="man-pages.html#cb119-4" aria-hidden="true" tabindex="-1"></a> <span class="dt">short</span> revents<span class="op">;</span> <span class="co">// when poll() returns, bitmap of events that occurred</span></span>
|
|||
|
|
<span id="cb119-5"><a href="man-pages.html#cb119-5" aria-hidden="true" tabindex="-1"></a><span class="op">};</span></span></code></pre></div>
|
|||
|
|
<p>Before calling <code>poll()</code>, load <code>fd</code> with the socket descriptor (if you set <code>fd</code> to a negative number, this <code>struct pollfd</code> is ignored and its <code>revents</code> field is set to zero) and then construct the <code>events</code> field by bitwise-ORing the following macros:</p>
|
|||
|
|
<table>
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 15%" />
|
|||
|
|
<col style="width: 84%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="header">
|
|||
|
|
<th>Macro</th>
|
|||
|
|
<th>Description</th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>POLLIN</code></td>
|
|||
|
|
<td>Alert me when data is ready to <code>recv()</code> on this socket.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>POLLOUT</code></td>
|
|||
|
|
<td>Alert me when I can <code>send()</code> data to this socket without blocking.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>POLLPRI</code></td>
|
|||
|
|
<td>Alert me when out-of-band data is ready to <code>recv()</code> on this socket.</td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
<p>Once the <code>poll()</code> call returns, the <code>revents</code> field will be constructed as a bitwise-OR of the above fields, telling you which descriptors actually have had that event occur. Additionally, these other fields might be present:</p>
|
|||
|
|
<table>
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 16%" />
|
|||
|
|
<col style="width: 83%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="header">
|
|||
|
|
<th>Macro</th>
|
|||
|
|
<th>Description</th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>POLLERR</code></td>
|
|||
|
|
<td>An error has occurred on this socket.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>POLLHUP</code></td>
|
|||
|
|
<td>The remote side of the connection hung up.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>POLLNVAL</code></td>
|
|||
|
|
<td>Something was wrong with the socket descriptor <code>fd</code>—maybe it’s uninitialized?</td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-16">Return Value</h3>
|
|||
|
|
<p>Returns the number of elements in the <code>ufds</code> array that have had event occur on them; this can be zero if the timeout occurred. Also returns <code>-1</code> on error (and <code>errno</code> will be set accordingly).</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-16">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb120"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb120-1"><a href="man-pages.html#cb120-1"></a><span class="dt">int</span> s1<span class="op">,</span> s2<span class="op">;</span></span>
|
|||
|
|
<span id="cb120-2"><a href="man-pages.html#cb120-2"></a><span class="dt">int</span> rv<span class="op">;</span></span>
|
|||
|
|
<span id="cb120-3"><a href="man-pages.html#cb120-3"></a><span class="dt">char</span> buf1<span class="op">[</span><span class="dv">256</span><span class="op">],</span> buf2<span class="op">[</span><span class="dv">256</span><span class="op">];</span></span>
|
|||
|
|
<span id="cb120-4"><a href="man-pages.html#cb120-4"></a><span class="kw">struct</span> pollfd ufds<span class="op">[</span><span class="dv">2</span><span class="op">];</span></span>
|
|||
|
|
<span id="cb120-5"><a href="man-pages.html#cb120-5"></a></span>
|
|||
|
|
<span id="cb120-6"><a href="man-pages.html#cb120-6"></a>s1 <span class="op">=</span> socket<span class="op">(</span>PF_INET<span class="op">,</span> SOCK_STREAM<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb120-7"><a href="man-pages.html#cb120-7"></a>s2 <span class="op">=</span> socket<span class="op">(</span>PF_INET<span class="op">,</span> SOCK_STREAM<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb120-8"><a href="man-pages.html#cb120-8"></a></span>
|
|||
|
|
<span id="cb120-9"><a href="man-pages.html#cb120-9"></a><span class="co">// pretend we've connected both to a server at this point</span></span>
|
|||
|
|
<span id="cb120-10"><a href="man-pages.html#cb120-10"></a><span class="co">//connect(s1, ...)...</span></span>
|
|||
|
|
<span id="cb120-11"><a href="man-pages.html#cb120-11"></a><span class="co">//connect(s2, ...)...</span></span>
|
|||
|
|
<span id="cb120-12"><a href="man-pages.html#cb120-12"></a></span>
|
|||
|
|
<span id="cb120-13"><a href="man-pages.html#cb120-13"></a><span class="co">// set up the array of file descriptors.</span></span>
|
|||
|
|
<span id="cb120-14"><a href="man-pages.html#cb120-14"></a><span class="co">//</span></span>
|
|||
|
|
<span id="cb120-15"><a href="man-pages.html#cb120-15"></a><span class="co">// in this example, we want to know when there's normal or out-of-band</span></span>
|
|||
|
|
<span id="cb120-16"><a href="man-pages.html#cb120-16"></a><span class="co">// data ready to be recv()'d...</span></span>
|
|||
|
|
<span id="cb120-17"><a href="man-pages.html#cb120-17"></a></span>
|
|||
|
|
<span id="cb120-18"><a href="man-pages.html#cb120-18"></a>ufds<span class="op">[</span><span class="dv">0</span><span class="op">].</span>fd <span class="op">=</span> s1<span class="op">;</span></span>
|
|||
|
|
<span id="cb120-19"><a href="man-pages.html#cb120-19"></a>ufds<span class="op">[</span><span class="dv">0</span><span class="op">].</span>events <span class="op">=</span> POLLIN <span class="op">|</span> POLLPRI<span class="op">;</span> <span class="co">// check for normal or out-of-band</span></span>
|
|||
|
|
<span id="cb120-20"><a href="man-pages.html#cb120-20"></a></span>
|
|||
|
|
<span id="cb120-21"><a href="man-pages.html#cb120-21"></a>ufds<span class="op">[</span><span class="dv">1</span><span class="op">].</span>fd <span class="op">=</span> s2<span class="op">;</span></span>
|
|||
|
|
<span id="cb120-22"><a href="man-pages.html#cb120-22"></a>ufds<span class="op">[</span><span class="dv">1</span><span class="op">].</span>events <span class="op">=</span> POLLIN<span class="op">;</span> <span class="co">// check for just normal data</span></span>
|
|||
|
|
<span id="cb120-23"><a href="man-pages.html#cb120-23"></a></span>
|
|||
|
|
<span id="cb120-24"><a href="man-pages.html#cb120-24"></a><span class="co">// wait for events on the sockets, 3.5 second timeout</span></span>
|
|||
|
|
<span id="cb120-25"><a href="man-pages.html#cb120-25"></a>rv <span class="op">=</span> poll<span class="op">(</span>ufds<span class="op">,</span> <span class="dv">2</span><span class="op">,</span> <span class="dv">3500</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb120-26"><a href="man-pages.html#cb120-26"></a></span>
|
|||
|
|
<span id="cb120-27"><a href="man-pages.html#cb120-27"></a><span class="cf">if</span> <span class="op">(</span>rv <span class="op">==</span> <span class="op">-</span><span class="dv">1</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb120-28"><a href="man-pages.html#cb120-28"></a> perror<span class="op">(</span><span class="st">"poll"</span><span class="op">);</span> <span class="co">// error occurred in poll()</span></span>
|
|||
|
|
<span id="cb120-29"><a href="man-pages.html#cb120-29"></a><span class="op">}</span> <span class="cf">else</span> <span class="cf">if</span> <span class="op">(</span>rv <span class="op">==</span> <span class="dv">0</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb120-30"><a href="man-pages.html#cb120-30"></a> printf<span class="op">(</span><span class="st">"Timeout occurred! No data after 3.5 seconds.</span><span class="sc">\n</span><span class="st">"</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb120-31"><a href="man-pages.html#cb120-31"></a><span class="op">}</span> <span class="cf">else</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb120-32"><a href="man-pages.html#cb120-32"></a> <span class="co">// check for events on s1:</span></span>
|
|||
|
|
<span id="cb120-33"><a href="man-pages.html#cb120-33"></a> <span class="cf">if</span> <span class="op">(</span>ufds<span class="op">[</span><span class="dv">0</span><span class="op">].</span>revents <span class="op">&</span> POLLIN<span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb120-34"><a href="man-pages.html#cb120-34"></a> recv<span class="op">(</span>s1<span class="op">,</span> buf1<span class="op">,</span> <span class="kw">sizeof</span> buf1<span class="op">,</span> <span class="dv">0</span><span class="op">);</span> <span class="co">// receive normal data</span></span>
|
|||
|
|
<span id="cb120-35"><a href="man-pages.html#cb120-35"></a> <span class="op">}</span></span>
|
|||
|
|
<span id="cb120-36"><a href="man-pages.html#cb120-36"></a> <span class="cf">if</span> <span class="op">(</span>ufds<span class="op">[</span><span class="dv">0</span><span class="op">].</span>revents <span class="op">&</span> POLLPRI<span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb120-37"><a href="man-pages.html#cb120-37"></a> recv<span class="op">(</span>s1<span class="op">,</span> buf1<span class="op">,</span> <span class="kw">sizeof</span> buf1<span class="op">,</span> MSG_OOB<span class="op">);</span> <span class="co">// out-of-band data</span></span>
|
|||
|
|
<span id="cb120-38"><a href="man-pages.html#cb120-38"></a> <span class="op">}</span></span>
|
|||
|
|
<span id="cb120-39"><a href="man-pages.html#cb120-39"></a></span>
|
|||
|
|
<span id="cb120-40"><a href="man-pages.html#cb120-40"></a> <span class="co">// check for events on s2:</span></span>
|
|||
|
|
<span id="cb120-41"><a href="man-pages.html#cb120-41"></a> <span class="cf">if</span> <span class="op">(</span>ufds<span class="op">[</span><span class="dv">1</span><span class="op">].</span>revents <span class="op">&</span> POLLIN<span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb120-42"><a href="man-pages.html#cb120-42"></a> recv<span class="op">(</span>s1<span class="op">,</span> buf2<span class="op">,</span> <span class="kw">sizeof</span> buf2<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb120-43"><a href="man-pages.html#cb120-43"></a> <span class="op">}</span></span>
|
|||
|
|
<span id="cb120-44"><a href="man-pages.html#cb120-44"></a><span class="op">}</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-15">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#selectman"><code>select()</code></a></p>
|
|||
|
|
<h2 data-number="9.18" id="recvman"><span class="header-section-number">9.18</span> <code>recv()</code>, <code>recvfrom()</code></h2>
|
|||
|
|
<p> </p>
|
|||
|
|
<p>Receive data on a socket</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-17">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb121"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb121-1"><a href="man-pages.html#cb121-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/types.h></span></span>
|
|||
|
|
<span id="cb121-2"><a href="man-pages.html#cb121-2" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb121-3"><a href="man-pages.html#cb121-3" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb121-4"><a href="man-pages.html#cb121-4" aria-hidden="true" tabindex="-1"></a><span class="dt">ssize_t</span> recv<span class="op">(</span><span class="dt">int</span> s<span class="op">,</span> <span class="dt">void</span> <span class="op">*</span>buf<span class="op">,</span> <span class="dt">size_t</span> len<span class="op">,</span> <span class="dt">int</span> flags<span class="op">);</span></span>
|
|||
|
|
<span id="cb121-5"><a href="man-pages.html#cb121-5" aria-hidden="true" tabindex="-1"></a><span class="dt">ssize_t</span> recvfrom<span class="op">(</span><span class="dt">int</span> s<span class="op">,</span> <span class="dt">void</span> <span class="op">*</span>buf<span class="op">,</span> <span class="dt">size_t</span> len<span class="op">,</span> <span class="dt">int</span> flags<span class="op">,</span></span>
|
|||
|
|
<span id="cb121-6"><a href="man-pages.html#cb121-6" aria-hidden="true" tabindex="-1"></a> <span class="kw">struct</span> sockaddr <span class="op">*</span>from<span class="op">,</span> socklen_t <span class="op">*</span>fromlen<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-17">Description</h3>
|
|||
|
|
<p>Once you have a socket up and connected, you can read incoming data from the remote side using the <code>recv()</code> (for TCP <code>SOCK_STREAM</code> sockets) and <code>recvfrom()</code> (for UDP <code>SOCK_DGRAM</code> sockets).</p>
|
|||
|
|
<p>Both functions take the socket descriptor <code>s</code>, a pointer to the buffer <code>buf</code>, the size (in bytes) of the buffer <code>len</code>, and a set of <code>flags</code> that control how the functions work.</p>
|
|||
|
|
<p>Additionally, the <code>recvfrom()</code> takes a <code>struct sockaddr*</code>, <code>from</code> that will tell you where the data came from, and will fill in <code>fromlen</code> with the size of <code>struct sockaddr</code>. (You must also initialize <code>fromlen</code> to be the size of <code>from</code> or <code>struct sockaddr</code>.)</p>
|
|||
|
|
<p>So what wondrous flags can you pass into this function? Here are some of them, but you should check your local man pages for more information and what is actually supported on your system. You bitwise-or these together, or just set <code>flags</code> to <code>0</code> if you want it to be a regular vanilla <code>recv()</code>.</p>
|
|||
|
|
<table>
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 20%" />
|
|||
|
|
<col style="width: 79%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="header">
|
|||
|
|
<th>Macro</th>
|
|||
|
|
<th>Description</th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>MSG_OOB</code></td>
|
|||
|
|
<td>Receive Out of Band data. This is how to get data that has been sent to you with the <code>MSG_OOB</code> flag in <code>send()</code>. As the receiving side, you will have had signal <code>SIGURG</code> raised telling you there is urgent data. In your handler for that signal, you could call <code>recv()</code> with this <code>MSG_OOB</code> flag.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>MSG_PEEK</code></td>
|
|||
|
|
<td>If you want to call <code>recv()</code> “just for pretend”, you can call it with this flag. This will tell you what’s waiting in the buffer for when you call <code>recv()</code> “for real” (i.e. <em>without</em> the <code>MSG_PEEK</code> flag. It’s like a sneak preview into the next <code>recv()</code> call.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>MSG_WAITALL</code></td>
|
|||
|
|
<td>Tell <code>recv()</code> to not return until all the data you specified in the <code>len</code> parameter. It will ignore your wishes in extreme circumstances, however, like if a signal interrupts the call or if some error occurs or if the remote side closes the connection, etc. Don’t be mad with it.</td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
<p>When you call <code>recv()</code>, it will block until there is some data to read. If you want to not block, set the socket to non-blocking or check with <code>select()</code> or <code>poll()</code> to see if there is incoming data before calling <code>recv()</code> or <code>recvfrom()</code>.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-17">Return Value</h3>
|
|||
|
|
<p>Returns the number of bytes actually received (which might be less than you requested in the <code>len</code> parameter), or <code>-1</code> on error (and <code>errno</code> will be set accordingly).</p>
|
|||
|
|
<p>If the remote side has closed the connection, <code>recv()</code> will return <code>0</code>. This is the normal method for determining if the remote side has closed the connection. Normality is good, rebel!</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-17">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb122"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb122-1"><a href="man-pages.html#cb122-1"></a><span class="co">// stream sockets and recv()</span></span>
|
|||
|
|
<span id="cb122-2"><a href="man-pages.html#cb122-2"></a></span>
|
|||
|
|
<span id="cb122-3"><a href="man-pages.html#cb122-3"></a><span class="kw">struct</span> addrinfo hints<span class="op">,</span> <span class="op">*</span>res<span class="op">;</span></span>
|
|||
|
|
<span id="cb122-4"><a href="man-pages.html#cb122-4"></a><span class="dt">int</span> sockfd<span class="op">;</span></span>
|
|||
|
|
<span id="cb122-5"><a href="man-pages.html#cb122-5"></a><span class="dt">char</span> buf<span class="op">[</span><span class="dv">512</span><span class="op">];</span></span>
|
|||
|
|
<span id="cb122-6"><a href="man-pages.html#cb122-6"></a><span class="dt">int</span> byte_count<span class="op">;</span></span>
|
|||
|
|
<span id="cb122-7"><a href="man-pages.html#cb122-7"></a></span>
|
|||
|
|
<span id="cb122-8"><a href="man-pages.html#cb122-8"></a><span class="co">// get host info, make socket, and connect it</span></span>
|
|||
|
|
<span id="cb122-9"><a href="man-pages.html#cb122-9"></a>memset<span class="op">(&</span>hints<span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="kw">sizeof</span> hints<span class="op">);</span></span>
|
|||
|
|
<span id="cb122-10"><a href="man-pages.html#cb122-10"></a>hints<span class="op">.</span>ai_family <span class="op">=</span> AF_UNSPEC<span class="op">;</span> <span class="co">// use IPv4 or IPv6, whichever</span></span>
|
|||
|
|
<span id="cb122-11"><a href="man-pages.html#cb122-11"></a>hints<span class="op">.</span>ai_socktype <span class="op">=</span> SOCK_STREAM<span class="op">;</span></span>
|
|||
|
|
<span id="cb122-12"><a href="man-pages.html#cb122-12"></a>getaddrinfo<span class="op">(</span><span class="st">"www.example.com"</span><span class="op">,</span> <span class="st">"3490"</span><span class="op">,</span> <span class="op">&</span>hints<span class="op">,</span> <span class="op">&</span>res<span class="op">);</span></span>
|
|||
|
|
<span id="cb122-13"><a href="man-pages.html#cb122-13"></a>sockfd <span class="op">=</span> socket<span class="op">(</span>res<span class="op">-></span>ai_family<span class="op">,</span> res<span class="op">-></span>ai_socktype<span class="op">,</span> res<span class="op">-></span>ai_protocol<span class="op">);</span></span>
|
|||
|
|
<span id="cb122-14"><a href="man-pages.html#cb122-14"></a>connect<span class="op">(</span>sockfd<span class="op">,</span> res<span class="op">-></span>ai_addr<span class="op">,</span> res<span class="op">-></span>ai_addrlen<span class="op">);</span></span>
|
|||
|
|
<span id="cb122-15"><a href="man-pages.html#cb122-15"></a></span>
|
|||
|
|
<span id="cb122-16"><a href="man-pages.html#cb122-16"></a><span class="co">// all right! now that we're connected, we can receive some data!</span></span>
|
|||
|
|
<span id="cb122-17"><a href="man-pages.html#cb122-17"></a>byte_count <span class="op">=</span> recv<span class="op">(</span>sockfd<span class="op">,</span> buf<span class="op">,</span> <span class="kw">sizeof</span> buf<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb122-18"><a href="man-pages.html#cb122-18"></a>printf<span class="op">(</span><span class="st">"recv()'d </span><span class="sc">%d</span><span class="st"> bytes of data in buf</span><span class="sc">\n</span><span class="st">"</span><span class="op">,</span> byte_count<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<div class="sourceCode" id="cb123"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb123-1"><a href="man-pages.html#cb123-1"></a><span class="co">// datagram sockets and recvfrom()</span></span>
|
|||
|
|
<span id="cb123-2"><a href="man-pages.html#cb123-2"></a></span>
|
|||
|
|
<span id="cb123-3"><a href="man-pages.html#cb123-3"></a><span class="kw">struct</span> addrinfo hints<span class="op">,</span> <span class="op">*</span>res<span class="op">;</span></span>
|
|||
|
|
<span id="cb123-4"><a href="man-pages.html#cb123-4"></a><span class="dt">int</span> sockfd<span class="op">;</span></span>
|
|||
|
|
<span id="cb123-5"><a href="man-pages.html#cb123-5"></a><span class="dt">int</span> byte_count<span class="op">;</span></span>
|
|||
|
|
<span id="cb123-6"><a href="man-pages.html#cb123-6"></a>socklen_t fromlen<span class="op">;</span></span>
|
|||
|
|
<span id="cb123-7"><a href="man-pages.html#cb123-7"></a><span class="kw">struct</span> sockaddr_storage addr<span class="op">;</span></span>
|
|||
|
|
<span id="cb123-8"><a href="man-pages.html#cb123-8"></a><span class="dt">char</span> buf<span class="op">[</span><span class="dv">512</span><span class="op">];</span></span>
|
|||
|
|
<span id="cb123-9"><a href="man-pages.html#cb123-9"></a><span class="dt">char</span> ipstr<span class="op">[</span>INET6_ADDRSTRLEN<span class="op">];</span></span>
|
|||
|
|
<span id="cb123-10"><a href="man-pages.html#cb123-10"></a></span>
|
|||
|
|
<span id="cb123-11"><a href="man-pages.html#cb123-11"></a><span class="co">// get host info, make socket, bind it to port 4950</span></span>
|
|||
|
|
<span id="cb123-12"><a href="man-pages.html#cb123-12"></a>memset<span class="op">(&</span>hints<span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="kw">sizeof</span> hints<span class="op">);</span></span>
|
|||
|
|
<span id="cb123-13"><a href="man-pages.html#cb123-13"></a>hints<span class="op">.</span>ai_family <span class="op">=</span> AF_UNSPEC<span class="op">;</span> <span class="co">// use IPv4 or IPv6, whichever</span></span>
|
|||
|
|
<span id="cb123-14"><a href="man-pages.html#cb123-14"></a>hints<span class="op">.</span>ai_socktype <span class="op">=</span> SOCK_DGRAM<span class="op">;</span></span>
|
|||
|
|
<span id="cb123-15"><a href="man-pages.html#cb123-15"></a>hints<span class="op">.</span>ai_flags <span class="op">=</span> AI_PASSIVE<span class="op">;</span></span>
|
|||
|
|
<span id="cb123-16"><a href="man-pages.html#cb123-16"></a>getaddrinfo<span class="op">(</span>NULL<span class="op">,</span> <span class="st">"4950"</span><span class="op">,</span> <span class="op">&</span>hints<span class="op">,</span> <span class="op">&</span>res<span class="op">);</span></span>
|
|||
|
|
<span id="cb123-17"><a href="man-pages.html#cb123-17"></a>sockfd <span class="op">=</span> socket<span class="op">(</span>res<span class="op">-></span>ai_family<span class="op">,</span> res<span class="op">-></span>ai_socktype<span class="op">,</span> res<span class="op">-></span>ai_protocol<span class="op">);</span></span>
|
|||
|
|
<span id="cb123-18"><a href="man-pages.html#cb123-18"></a>bind<span class="op">(</span>sockfd<span class="op">,</span> res<span class="op">-></span>ai_addr<span class="op">,</span> res<span class="op">-></span>ai_addrlen<span class="op">);</span></span>
|
|||
|
|
<span id="cb123-19"><a href="man-pages.html#cb123-19"></a></span>
|
|||
|
|
<span id="cb123-20"><a href="man-pages.html#cb123-20"></a><span class="co">// no need to accept(), just recvfrom():</span></span>
|
|||
|
|
<span id="cb123-21"><a href="man-pages.html#cb123-21"></a></span>
|
|||
|
|
<span id="cb123-22"><a href="man-pages.html#cb123-22"></a>fromlen <span class="op">=</span> <span class="kw">sizeof</span> addr<span class="op">;</span></span>
|
|||
|
|
<span id="cb123-23"><a href="man-pages.html#cb123-23"></a>byte_count <span class="op">=</span> recvfrom<span class="op">(</span>sockfd<span class="op">,</span> buf<span class="op">,</span> <span class="kw">sizeof</span> buf<span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="op">&</span>addr<span class="op">,</span> <span class="op">&</span>fromlen<span class="op">);</span></span>
|
|||
|
|
<span id="cb123-24"><a href="man-pages.html#cb123-24"></a></span>
|
|||
|
|
<span id="cb123-25"><a href="man-pages.html#cb123-25"></a>printf<span class="op">(</span><span class="st">"recv()'d </span><span class="sc">%d</span><span class="st"> bytes of data in buf</span><span class="sc">\n</span><span class="st">"</span><span class="op">,</span> byte_count<span class="op">);</span></span>
|
|||
|
|
<span id="cb123-26"><a href="man-pages.html#cb123-26"></a>printf<span class="op">(</span><span class="st">"from IP address </span><span class="sc">%s\n</span><span class="st">"</span><span class="op">,</span></span>
|
|||
|
|
<span id="cb123-27"><a href="man-pages.html#cb123-27"></a> inet_ntop<span class="op">(</span>addr<span class="op">.</span>ss_family<span class="op">,</span></span>
|
|||
|
|
<span id="cb123-28"><a href="man-pages.html#cb123-28"></a> addr<span class="op">.</span>ss_family <span class="op">==</span> AF_INET<span class="op">?</span></span>
|
|||
|
|
<span id="cb123-29"><a href="man-pages.html#cb123-29"></a> <span class="op">((</span><span class="kw">struct</span> sockadd_in <span class="op">*)&</span>addr<span class="op">)-></span>sin_addr<span class="op">:</span></span>
|
|||
|
|
<span id="cb123-30"><a href="man-pages.html#cb123-30"></a> <span class="op">((</span><span class="kw">struct</span> sockadd_in6 <span class="op">*)&</span>addr<span class="op">)-></span>sin6_addr<span class="op">,</span></span>
|
|||
|
|
<span id="cb123-31"><a href="man-pages.html#cb123-31"></a> ipstr<span class="op">,</span> <span class="kw">sizeof</span> ipstr<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-16">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#sendman"><code>send()</code></a>, <a href="man-pages.html#sendman"><code>sendto()</code></a>, <a href="man-pages.html#selectman"><code>select()</code></a>, <a href="man-pages.html#pollman"><code>poll()</code></a>, <a href="slightly-advanced-techniques.html#blocking">Blocking</a></p>
|
|||
|
|
<h2 data-number="9.19" id="selectman"><span class="header-section-number">9.19</span> <code>select()</code></h2>
|
|||
|
|
<p></p>
|
|||
|
|
<p>Check if sockets descriptors are ready to read/write</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-18">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb124"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb124-1"><a href="man-pages.html#cb124-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/select.h></span></span>
|
|||
|
|
<span id="cb124-2"><a href="man-pages.html#cb124-2" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb124-3"><a href="man-pages.html#cb124-3" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> select<span class="op">(</span><span class="dt">int</span> n<span class="op">,</span> fd_set <span class="op">*</span>readfds<span class="op">,</span> fd_set <span class="op">*</span>writefds<span class="op">,</span> fd_set <span class="op">*</span>exceptfds<span class="op">,</span></span>
|
|||
|
|
<span id="cb124-4"><a href="man-pages.html#cb124-4" aria-hidden="true" tabindex="-1"></a> <span class="kw">struct</span> timeval <span class="op">*</span>timeout<span class="op">);</span></span>
|
|||
|
|
<span id="cb124-5"><a href="man-pages.html#cb124-5" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb124-6"><a href="man-pages.html#cb124-6" aria-hidden="true" tabindex="-1"></a>FD_SET<span class="op">(</span><span class="dt">int</span> fd<span class="op">,</span> fd_set <span class="op">*</span>set<span class="op">);</span></span>
|
|||
|
|
<span id="cb124-7"><a href="man-pages.html#cb124-7" aria-hidden="true" tabindex="-1"></a>FD_CLR<span class="op">(</span><span class="dt">int</span> fd<span class="op">,</span> fd_set <span class="op">*</span>set<span class="op">);</span></span>
|
|||
|
|
<span id="cb124-8"><a href="man-pages.html#cb124-8" aria-hidden="true" tabindex="-1"></a>FD_ISSET<span class="op">(</span><span class="dt">int</span> fd<span class="op">,</span> fd_set <span class="op">*</span>set<span class="op">);</span></span>
|
|||
|
|
<span id="cb124-9"><a href="man-pages.html#cb124-9" aria-hidden="true" tabindex="-1"></a>FD_ZERO<span class="op">(</span>fd_set <span class="op">*</span>set<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-18">Description</h3>
|
|||
|
|
<p>The <code>select()</code> function gives you a way to simultaneously check multiple sockets to see if they have data waiting to be <code>recv()</code>d, or if you can <code>send()</code> data to them without blocking, or if some exception has occurred.</p>
|
|||
|
|
<p>You populate your sets of socket descriptors using the macros, like <code>FD_SET()</code>, above. Once you have the set, you pass it into the function as one of the following parameters: <code>readfds</code> if you want to know when any of the sockets in the set is ready to <code>recv()</code> data, <code>writefds</code> if any of the sockets is ready to <code>send()</code> data to, and/or <code>exceptfds</code> if you need to know when an exception (error) occurs on any of the sockets. Any or all of these parameters can be <code>NULL</code> if you’re not interested in those types of events. After <code>select()</code> returns, the values in the sets will be changed to show which are ready for reading or writing, and which have exceptions.</p>
|
|||
|
|
<p>The first parameter, <code>n</code> is the highest-numbered socket descriptor (they’re just <code>int</code>s, remember?) plus one.</p>
|
|||
|
|
<p>Lastly, the <code>struct timeval</code>, <code>timeout</code>, at the end—this lets you tell <code>select()</code> how long to check these sets for. It’ll return after the timeout, or when an event occurs, whichever is first. The <code>struct timeval</code> has two fields: <code>tv_sec</code> is the number of seconds, to which is added <code>tv_usec</code>, the number of microseconds (1,000,000 microseconds in a second).</p>
|
|||
|
|
<p>The helper macros do the following:</p>
|
|||
|
|
<table>
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 46%" />
|
|||
|
|
<col style="width: 53%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="header">
|
|||
|
|
<th>Macro</th>
|
|||
|
|
<th>Description</th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>FD_SET(int fd, fd_set *set);</code></td>
|
|||
|
|
<td>Add <code>fd</code> to the <code>set</code>.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>FD_CLR(int fd, fd_set *set);</code></td>
|
|||
|
|
<td>Remove <code>fd</code> from the <code>set</code>.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>FD_ISSET(int fd, fd_set *set);</code></td>
|
|||
|
|
<td>Return true if <code>fd</code> is in the <code>set</code>.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>FD_ZERO(fd_set *set);</code></td>
|
|||
|
|
<td>Clear all entries from the <code>set</code>.</td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
<p>Note for Linux users: Linux’s <code>select()</code> can return “ready-to-read” and then not actually be ready to read, thus causing the subsequent <code>read()</code> call to block. You can work around this bug by setting <code>O_NONBLOCK</code> flag on the receiving socket so it errors with <code>EWOULDBLOCK</code>, then ignoring this error if it occurs. See the <a href="man-pages.html#fcntlman"><code>fcntl()</code> man page</a> for more info on setting a socket to non-blocking.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-18">Return Value</h3>
|
|||
|
|
<p>Returns the number of descriptors in the set on success, <code>0</code> if the timeout was reached, or <code>-1</code> on error (and <code>errno</code> will be set accordingly). Also, the sets are modified to show which sockets are ready.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-18">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb125"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb125-1"><a href="man-pages.html#cb125-1"></a><span class="dt">int</span> s1<span class="op">,</span> s2<span class="op">,</span> n<span class="op">;</span></span>
|
|||
|
|
<span id="cb125-2"><a href="man-pages.html#cb125-2"></a>fd_set readfds<span class="op">;</span></span>
|
|||
|
|
<span id="cb125-3"><a href="man-pages.html#cb125-3"></a><span class="kw">struct</span> timeval tv<span class="op">;</span></span>
|
|||
|
|
<span id="cb125-4"><a href="man-pages.html#cb125-4"></a><span class="dt">char</span> buf1<span class="op">[</span><span class="dv">256</span><span class="op">],</span> buf2<span class="op">[</span><span class="dv">256</span><span class="op">];</span></span>
|
|||
|
|
<span id="cb125-5"><a href="man-pages.html#cb125-5"></a></span>
|
|||
|
|
<span id="cb125-6"><a href="man-pages.html#cb125-6"></a><span class="co">// pretend we've connected both to a server at this point</span></span>
|
|||
|
|
<span id="cb125-7"><a href="man-pages.html#cb125-7"></a><span class="co">//s1 = socket(...);</span></span>
|
|||
|
|
<span id="cb125-8"><a href="man-pages.html#cb125-8"></a><span class="co">//s2 = socket(...);</span></span>
|
|||
|
|
<span id="cb125-9"><a href="man-pages.html#cb125-9"></a><span class="co">//connect(s1, ...)...</span></span>
|
|||
|
|
<span id="cb125-10"><a href="man-pages.html#cb125-10"></a><span class="co">//connect(s2, ...)...</span></span>
|
|||
|
|
<span id="cb125-11"><a href="man-pages.html#cb125-11"></a></span>
|
|||
|
|
<span id="cb125-12"><a href="man-pages.html#cb125-12"></a><span class="co">// clear the set ahead of time</span></span>
|
|||
|
|
<span id="cb125-13"><a href="man-pages.html#cb125-13"></a>FD_ZERO<span class="op">(&</span>readfds<span class="op">);</span></span>
|
|||
|
|
<span id="cb125-14"><a href="man-pages.html#cb125-14"></a></span>
|
|||
|
|
<span id="cb125-15"><a href="man-pages.html#cb125-15"></a><span class="co">// add our descriptors to the set</span></span>
|
|||
|
|
<span id="cb125-16"><a href="man-pages.html#cb125-16"></a>FD_SET<span class="op">(</span>s1<span class="op">,</span> <span class="op">&</span>readfds<span class="op">);</span></span>
|
|||
|
|
<span id="cb125-17"><a href="man-pages.html#cb125-17"></a>FD_SET<span class="op">(</span>s2<span class="op">,</span> <span class="op">&</span>readfds<span class="op">);</span></span>
|
|||
|
|
<span id="cb125-18"><a href="man-pages.html#cb125-18"></a></span>
|
|||
|
|
<span id="cb125-19"><a href="man-pages.html#cb125-19"></a><span class="co">// since we got s2 second, it's the "greater", so we use that for</span></span>
|
|||
|
|
<span id="cb125-20"><a href="man-pages.html#cb125-20"></a><span class="co">// the n param in select()</span></span>
|
|||
|
|
<span id="cb125-21"><a href="man-pages.html#cb125-21"></a>n <span class="op">=</span> s2 <span class="op">+</span> <span class="dv">1</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb125-22"><a href="man-pages.html#cb125-22"></a></span>
|
|||
|
|
<span id="cb125-23"><a href="man-pages.html#cb125-23"></a><span class="co">// wait until either socket has data ready to be recv()d (timeout 10.5 secs)</span></span>
|
|||
|
|
<span id="cb125-24"><a href="man-pages.html#cb125-24"></a>tv<span class="op">.</span>tv_sec <span class="op">=</span> <span class="dv">10</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb125-25"><a href="man-pages.html#cb125-25"></a>tv<span class="op">.</span>tv_usec <span class="op">=</span> <span class="dv">500000</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb125-26"><a href="man-pages.html#cb125-26"></a>rv <span class="op">=</span> select<span class="op">(</span>n<span class="op">,</span> <span class="op">&</span>readfds<span class="op">,</span> NULL<span class="op">,</span> NULL<span class="op">,</span> <span class="op">&</span>tv<span class="op">);</span></span>
|
|||
|
|
<span id="cb125-27"><a href="man-pages.html#cb125-27"></a></span>
|
|||
|
|
<span id="cb125-28"><a href="man-pages.html#cb125-28"></a><span class="cf">if</span> <span class="op">(</span>rv <span class="op">==</span> <span class="op">-</span><span class="dv">1</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb125-29"><a href="man-pages.html#cb125-29"></a> perror<span class="op">(</span><span class="st">"select"</span><span class="op">);</span> <span class="co">// error occurred in select()</span></span>
|
|||
|
|
<span id="cb125-30"><a href="man-pages.html#cb125-30"></a><span class="op">}</span> <span class="cf">else</span> <span class="cf">if</span> <span class="op">(</span>rv <span class="op">==</span> <span class="dv">0</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb125-31"><a href="man-pages.html#cb125-31"></a> printf<span class="op">(</span><span class="st">"Timeout occurred! No data after 10.5 seconds.</span><span class="sc">\n</span><span class="st">"</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb125-32"><a href="man-pages.html#cb125-32"></a><span class="op">}</span> <span class="cf">else</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb125-33"><a href="man-pages.html#cb125-33"></a> <span class="co">// one or both of the descriptors have data</span></span>
|
|||
|
|
<span id="cb125-34"><a href="man-pages.html#cb125-34"></a> <span class="cf">if</span> <span class="op">(</span>FD_ISSET<span class="op">(</span>s1<span class="op">,</span> <span class="op">&</span>readfds<span class="op">))</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb125-35"><a href="man-pages.html#cb125-35"></a> recv<span class="op">(</span>s1<span class="op">,</span> buf1<span class="op">,</span> <span class="kw">sizeof</span> buf1<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb125-36"><a href="man-pages.html#cb125-36"></a> <span class="op">}</span></span>
|
|||
|
|
<span id="cb125-37"><a href="man-pages.html#cb125-37"></a> <span class="cf">if</span> <span class="op">(</span>FD_ISSET<span class="op">(</span>s2<span class="op">,</span> <span class="op">&</span>readfds<span class="op">))</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb125-38"><a href="man-pages.html#cb125-38"></a> recv<span class="op">(</span>s2<span class="op">,</span> buf2<span class="op">,</span> <span class="kw">sizeof</span> buf2<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb125-39"><a href="man-pages.html#cb125-39"></a> <span class="op">}</span></span>
|
|||
|
|
<span id="cb125-40"><a href="man-pages.html#cb125-40"></a><span class="op">}</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-17">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#pollman"><code>poll()</code></a></p>
|
|||
|
|
<h2 data-number="9.20" id="setsockoptman"><span class="header-section-number">9.20</span> <code>setsockopt()</code>, <code>getsockopt()</code></h2>
|
|||
|
|
<p> </p>
|
|||
|
|
<p>Set various options for a socket</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-19">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb126"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb126-1"><a href="man-pages.html#cb126-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/types.h></span></span>
|
|||
|
|
<span id="cb126-2"><a href="man-pages.html#cb126-2" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb126-3"><a href="man-pages.html#cb126-3" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb126-4"><a href="man-pages.html#cb126-4" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> getsockopt<span class="op">(</span><span class="dt">int</span> s<span class="op">,</span> <span class="dt">int</span> level<span class="op">,</span> <span class="dt">int</span> optname<span class="op">,</span> <span class="dt">void</span> <span class="op">*</span>optval<span class="op">,</span></span>
|
|||
|
|
<span id="cb126-5"><a href="man-pages.html#cb126-5" aria-hidden="true" tabindex="-1"></a> socklen_t <span class="op">*</span>optlen<span class="op">);</span></span>
|
|||
|
|
<span id="cb126-6"><a href="man-pages.html#cb126-6" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> setsockopt<span class="op">(</span><span class="dt">int</span> s<span class="op">,</span> <span class="dt">int</span> level<span class="op">,</span> <span class="dt">int</span> optname<span class="op">,</span> <span class="dt">const</span> <span class="dt">void</span> <span class="op">*</span>optval<span class="op">,</span></span>
|
|||
|
|
<span id="cb126-7"><a href="man-pages.html#cb126-7" aria-hidden="true" tabindex="-1"></a> socklen_t optlen<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-19">Description</h3>
|
|||
|
|
<p>Sockets are fairly configurable beasts. In fact, they are so configurable, I’m not even going to cover it all here. It’s probably system-dependent anyway. But I will talk about the basics.</p>
|
|||
|
|
<p>Obviously, these functions get and set certain options on a socket. On a Linux box, all the socket information is in the man page for socket in section 7. (Type: “<code>man 7 socket</code>” to get all these goodies.)</p>
|
|||
|
|
<p>As for parameters, <code>s</code> is the socket you’re talking about, level should be set to <code>SOL_SOCKET</code>. Then you set the <code>optname</code> to the name you’re interested in. Again, see your man page for all the options, but here are some of the most fun ones:</p>
|
|||
|
|
<table>
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 26%" />
|
|||
|
|
<col style="width: 73%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="header">
|
|||
|
|
<th><code>optname</code></th>
|
|||
|
|
<th>Description</th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>SO_BINDTODEVICE</code></td>
|
|||
|
|
<td>Bind this socket to a symbolic device name like <code>eth0</code> instead of using <code>bind()</code> to bind it to an IP address. Type the command <code>ifconfig</code> under Unix to see the device names.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>SO_REUSEADDR</code></td>
|
|||
|
|
<td>Allows other sockets to <code>bind()</code> to this port, unless there is an active listening socket bound to the port already. This enables you to get around those “Address already in use” error messages when you try to restart your server after a crash.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>SOCK_DGRAM</code></td>
|
|||
|
|
<td>Allows UDP datagram (<code>SOCK_DGRAM</code>) sockets to send and receive packets sent to and from the broadcast address. Does nothing—<em>NOTHING!!</em>—to TCP stream sockets! Hahaha!</td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
<p>As for the parameter <code>optval</code>, it’s usually a pointer to an <code>int</code> indicating the value in question. For booleans, zero is false, and non-zero is true. And that’s an absolute fact, unless it’s different on your system. If there is no parameter to be passed, <code>optval</code> can be <code>NULL</code>.</p>
|
|||
|
|
<p>The final parameter, <code>optlen</code>, should be set to the length of <code>optval</code>, probably <code>sizeof(int)</code>, but varies depending on the option. Note that in the case of <code>getsockopt()</code>, this is a pointer to a <code>socklen_t</code>, and it specifies the maximum size object that will be stored in <code>optval</code> (to prevent buffer overflows). And <code>getsockopt()</code> will modify the value of <code>optlen</code> to reflect the number of bytes actually set.</p>
|
|||
|
|
<p><strong>Warning</strong>: on some systems (notably Sun and Windows), the option can be a <code>char</code> instead of an <code>int</code>, and is set to, for example, a character value of <code>'1'</code> instead of an <code>int</code> value of <code>1</code>. Again, check your own man pages for more info with “<code>man setsockopt</code>” and “<code>man 7 socket</code>”!</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-19">Return Value</h3>
|
|||
|
|
<p>Returns zero on success, or <code>-1</code> on error (and <code>errno</code> will be set accordingly).</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-19">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb127"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb127-1"><a href="man-pages.html#cb127-1"></a><span class="dt">int</span> optval<span class="op">;</span></span>
|
|||
|
|
<span id="cb127-2"><a href="man-pages.html#cb127-2"></a><span class="dt">int</span> optlen<span class="op">;</span></span>
|
|||
|
|
<span id="cb127-3"><a href="man-pages.html#cb127-3"></a><span class="dt">char</span> <span class="op">*</span>optval2<span class="op">;</span></span>
|
|||
|
|
<span id="cb127-4"><a href="man-pages.html#cb127-4"></a></span>
|
|||
|
|
<span id="cb127-5"><a href="man-pages.html#cb127-5"></a><span class="co">// set SO_REUSEADDR on a socket to true (1):</span></span>
|
|||
|
|
<span id="cb127-6"><a href="man-pages.html#cb127-6"></a>optval <span class="op">=</span> <span class="dv">1</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb127-7"><a href="man-pages.html#cb127-7"></a>setsockopt<span class="op">(</span>s1<span class="op">,</span> SOL_SOCKET<span class="op">,</span> SO_REUSEADDR<span class="op">,</span> <span class="op">&</span>optval<span class="op">,</span> <span class="kw">sizeof</span> optval<span class="op">);</span></span>
|
|||
|
|
<span id="cb127-8"><a href="man-pages.html#cb127-8"></a></span>
|
|||
|
|
<span id="cb127-9"><a href="man-pages.html#cb127-9"></a><span class="co">// bind a socket to a device name (might not work on all systems):</span></span>
|
|||
|
|
<span id="cb127-10"><a href="man-pages.html#cb127-10"></a>optval2 <span class="op">=</span> <span class="st">"eth1"</span><span class="op">;</span> <span class="co">// 4 bytes long, so 4, below:</span></span>
|
|||
|
|
<span id="cb127-11"><a href="man-pages.html#cb127-11"></a>setsockopt<span class="op">(</span>s2<span class="op">,</span> SOL_SOCKET<span class="op">,</span> SO_BINDTODEVICE<span class="op">,</span> optval2<span class="op">,</span> <span class="dv">4</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb127-12"><a href="man-pages.html#cb127-12"></a></span>
|
|||
|
|
<span id="cb127-13"><a href="man-pages.html#cb127-13"></a><span class="co">// see if the SO_BROADCAST flag is set:</span></span>
|
|||
|
|
<span id="cb127-14"><a href="man-pages.html#cb127-14"></a>getsockopt<span class="op">(</span>s3<span class="op">,</span> SOL_SOCKET<span class="op">,</span> SO_BROADCAST<span class="op">,</span> <span class="op">&</span>optval<span class="op">,</span> <span class="op">&</span>optlen<span class="op">);</span></span>
|
|||
|
|
<span id="cb127-15"><a href="man-pages.html#cb127-15"></a><span class="cf">if</span> <span class="op">(</span>optval <span class="op">!=</span> <span class="dv">0</span><span class="op">)</span> <span class="op">{</span></span>
|
|||
|
|
<span id="cb127-16"><a href="man-pages.html#cb127-16"></a> print<span class="op">(</span><span class="st">"SO_BROADCAST enabled on s3!</span><span class="sc">\n</span><span class="st">"</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb127-17"><a href="man-pages.html#cb127-17"></a><span class="op">}</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-18">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#fcntlman"><code>fcntl()</code></a></p>
|
|||
|
|
<h2 data-number="9.21" id="sendman"><span class="header-section-number">9.21</span> <code>send()</code>, <code>sendto()</code></h2>
|
|||
|
|
<p> </p>
|
|||
|
|
<p>Send data out over a socket</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-20">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb128"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb128-1"><a href="man-pages.html#cb128-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/types.h></span></span>
|
|||
|
|
<span id="cb128-2"><a href="man-pages.html#cb128-2" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb128-3"><a href="man-pages.html#cb128-3" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb128-4"><a href="man-pages.html#cb128-4" aria-hidden="true" tabindex="-1"></a><span class="dt">ssize_t</span> send<span class="op">(</span><span class="dt">int</span> s<span class="op">,</span> <span class="dt">const</span> <span class="dt">void</span> <span class="op">*</span>buf<span class="op">,</span> <span class="dt">size_t</span> len<span class="op">,</span> <span class="dt">int</span> flags<span class="op">);</span></span>
|
|||
|
|
<span id="cb128-5"><a href="man-pages.html#cb128-5" aria-hidden="true" tabindex="-1"></a><span class="dt">ssize_t</span> sendto<span class="op">(</span><span class="dt">int</span> s<span class="op">,</span> <span class="dt">const</span> <span class="dt">void</span> <span class="op">*</span>buf<span class="op">,</span> <span class="dt">size_t</span> len<span class="op">,</span></span>
|
|||
|
|
<span id="cb128-6"><a href="man-pages.html#cb128-6" aria-hidden="true" tabindex="-1"></a> <span class="dt">int</span> flags<span class="op">,</span> <span class="dt">const</span> <span class="kw">struct</span> sockaddr <span class="op">*</span>to<span class="op">,</span></span>
|
|||
|
|
<span id="cb128-7"><a href="man-pages.html#cb128-7" aria-hidden="true" tabindex="-1"></a> socklen_t tolen<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-20">Description</h3>
|
|||
|
|
<p>These functions send data to a socket. Generally speaking, <code>send()</code> is used for TCP <code>SOCK_STREAM</code> connected sockets, and <code>sendto()</code> is used for UDP <code>SOCK_DGRAM</code> unconnected datagram sockets. With the unconnected sockets, you must specify the destination of a packet each time you send one, and that’s why the last parameters of <code>sendto()</code> define where the packet is going.</p>
|
|||
|
|
<p>With both <code>send()</code> and <code>sendto()</code>, the parameter <code>s</code> is the socket, <code>buf</code> is a pointer to the data you want to send, <code>len</code> is the number of bytes you want to send, and <code>flags</code> allows you to specify more information about how the data is to be sent. Set <code>flags</code> to zero if you want it to be “normal” data. Here are some of the commonly used flags, but check your local <code>send()</code> man pages for more details:</p>
|
|||
|
|
<table>
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 23%" />
|
|||
|
|
<col style="width: 76%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="header">
|
|||
|
|
<th>Macro</th>
|
|||
|
|
<th>Description</th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>MSG_OOB</code></td>
|
|||
|
|
<td>Send as “out of band” data. TCP supports this, and it’s a way to tell the receiving system that this data has a higher priority than the normal data. The receiver will receive the signal <code>SIGURG</code> and it can then receive this data without first receiving all the rest of the normal data in the queue.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>MSG_DONTROUTE</code></td>
|
|||
|
|
<td>Don’t send this data over a router, just keep it local.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>MSG_DONTWAIT</code></td>
|
|||
|
|
<td>If <code>send()</code> would block because outbound traffic is clogged, have it return <code>EAGAIN</code>. This is like a “enable non-blocking just for this send.” See the section on <a href="slightly-advanced-techniques.html#blocking">blocking</a> for more details.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>MSG_NOSIGNAL</code></td>
|
|||
|
|
<td>If you <code>send()</code> to a remote host which is no longer <code>recv()</code>ing, you’ll typically get the signal <code>SIGPIPE</code>. Adding this flag prevents that signal from being raised.</td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-20">Return Value</h3>
|
|||
|
|
<p>Returns the number of bytes actually sent, or <code>-1</code> on error (and <code>errno</code> will be set accordingly). Note that the number of bytes actually sent might be less than the number you asked it to send! See the section on <a href="slightly-advanced-techniques.html#sendall">handling partial <code>send()</code>s</a> for a helper function to get around this.</p>
|
|||
|
|
<p>Also, if the socket has been closed by either side, the process calling <code>send()</code> will get the signal <code>SIGPIPE</code>. (Unless <code>send()</code> was called with the <code>MSG_NOSIGNAL</code> flag.)</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-20">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb129"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb129-1"><a href="man-pages.html#cb129-1"></a><span class="dt">int</span> spatula_count <span class="op">=</span> <span class="dv">3490</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb129-2"><a href="man-pages.html#cb129-2"></a><span class="dt">char</span> <span class="op">*</span>secret_message <span class="op">=</span> <span class="st">"The Cheese is in The Toaster"</span><span class="op">;</span></span>
|
|||
|
|
<span id="cb129-3"><a href="man-pages.html#cb129-3"></a></span>
|
|||
|
|
<span id="cb129-4"><a href="man-pages.html#cb129-4"></a><span class="dt">int</span> stream_socket<span class="op">,</span> dgram_socket<span class="op">;</span></span>
|
|||
|
|
<span id="cb129-5"><a href="man-pages.html#cb129-5"></a><span class="kw">struct</span> sockaddr_in dest<span class="op">;</span></span>
|
|||
|
|
<span id="cb129-6"><a href="man-pages.html#cb129-6"></a><span class="dt">int</span> temp<span class="op">;</span></span>
|
|||
|
|
<span id="cb129-7"><a href="man-pages.html#cb129-7"></a></span>
|
|||
|
|
<span id="cb129-8"><a href="man-pages.html#cb129-8"></a><span class="co">// first with TCP stream sockets:</span></span>
|
|||
|
|
<span id="cb129-9"><a href="man-pages.html#cb129-9"></a></span>
|
|||
|
|
<span id="cb129-10"><a href="man-pages.html#cb129-10"></a><span class="co">// assume sockets are made and connected</span></span>
|
|||
|
|
<span id="cb129-11"><a href="man-pages.html#cb129-11"></a><span class="co">//stream_socket = socket(...</span></span>
|
|||
|
|
<span id="cb129-12"><a href="man-pages.html#cb129-12"></a><span class="co">//connect(stream_socket, ...</span></span>
|
|||
|
|
<span id="cb129-13"><a href="man-pages.html#cb129-13"></a></span>
|
|||
|
|
<span id="cb129-14"><a href="man-pages.html#cb129-14"></a><span class="co">// convert to network byte order</span></span>
|
|||
|
|
<span id="cb129-15"><a href="man-pages.html#cb129-15"></a>temp <span class="op">=</span> htonl<span class="op">(</span>spatula_count<span class="op">);</span></span>
|
|||
|
|
<span id="cb129-16"><a href="man-pages.html#cb129-16"></a><span class="co">// send data normally:</span></span>
|
|||
|
|
<span id="cb129-17"><a href="man-pages.html#cb129-17"></a>send<span class="op">(</span>stream_socket<span class="op">,</span> <span class="op">&</span>temp<span class="op">,</span> <span class="kw">sizeof</span> temp<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb129-18"><a href="man-pages.html#cb129-18"></a></span>
|
|||
|
|
<span id="cb129-19"><a href="man-pages.html#cb129-19"></a><span class="co">// send secret message out of band:</span></span>
|
|||
|
|
<span id="cb129-20"><a href="man-pages.html#cb129-20"></a>send<span class="op">(</span>stream_socket<span class="op">,</span> secret_message<span class="op">,</span> strlen<span class="op">(</span>secret_message<span class="op">)+</span><span class="dv">1</span><span class="op">,</span> MSG_OOB<span class="op">);</span></span>
|
|||
|
|
<span id="cb129-21"><a href="man-pages.html#cb129-21"></a></span>
|
|||
|
|
<span id="cb129-22"><a href="man-pages.html#cb129-22"></a><span class="co">// now with UDP datagram sockets:</span></span>
|
|||
|
|
<span id="cb129-23"><a href="man-pages.html#cb129-23"></a><span class="co">//getaddrinfo(...</span></span>
|
|||
|
|
<span id="cb129-24"><a href="man-pages.html#cb129-24"></a><span class="co">//dest = ... // assume "dest" holds the address of the destination</span></span>
|
|||
|
|
<span id="cb129-25"><a href="man-pages.html#cb129-25"></a><span class="co">//dgram_socket = socket(...</span></span>
|
|||
|
|
<span id="cb129-26"><a href="man-pages.html#cb129-26"></a></span>
|
|||
|
|
<span id="cb129-27"><a href="man-pages.html#cb129-27"></a><span class="co">// send secret message normally:</span></span>
|
|||
|
|
<span id="cb129-28"><a href="man-pages.html#cb129-28"></a>sendto<span class="op">(</span>dgram_socket<span class="op">,</span> secret_message<span class="op">,</span> strlen<span class="op">(</span>secret_message<span class="op">)+</span><span class="dv">1</span><span class="op">,</span> <span class="dv">0</span><span class="op">,</span> </span>
|
|||
|
|
<span id="cb129-29"><a href="man-pages.html#cb129-29"></a> <span class="op">(</span><span class="kw">struct</span> sockaddr<span class="op">*)&</span>dest<span class="op">,</span> <span class="kw">sizeof</span> dest<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-19">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#recvman"><code>recv()</code></a>, <a href="man-pages.html#recvman"><code>recvfrom()</code></a></p>
|
|||
|
|
<h2 data-number="9.22" id="shutdownman"><span class="header-section-number">9.22</span> <code>shutdown()</code></h2>
|
|||
|
|
<p></p>
|
|||
|
|
<p>Stop further sends and receives on a socket</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-21">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb130"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb130-1"><a href="man-pages.html#cb130-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb130-2"><a href="man-pages.html#cb130-2" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb130-3"><a href="man-pages.html#cb130-3" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> shutdown<span class="op">(</span><span class="dt">int</span> s<span class="op">,</span> <span class="dt">int</span> how<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-21">Description</h3>
|
|||
|
|
<p>That’s it! I’ve had it! No more <code>send()</code>s are allowed on this socket, but I still want to <code>recv()</code> data on it! Or vice-versa! How can I do this?</p>
|
|||
|
|
<p>When you <code>close()</code> a socket descriptor, it closes both sides of the socket for reading and writing, and frees the socket descriptor. If you just want to close one side or the other, you can use this <code>shutdown()</code> call.</p>
|
|||
|
|
<p>As for parameters, <code>s</code> is obviously the socket you want to perform this action on, and what action that is can be specified with the <code>how</code> parameter. <code>how</code> can be <code>SHUT_RD</code> to prevent further <code>recv()</code>s, <code>SHUT_WR</code> to prohibit further <code>send()</code>s, or <code>SHUT_RDWR</code> to do both.</p>
|
|||
|
|
<p>Note that <code>shutdown()</code> doesn’t free up the socket descriptor, so you still have to eventually <code>close()</code> the socket even if it has been fully shut down.</p>
|
|||
|
|
<p>This is a rarely used system call.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-21">Return Value</h3>
|
|||
|
|
<p>Returns zero on success, or <code>-1</code> on error (and <code>errno</code> will be set accordingly).</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-21">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb131"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb131-1"><a href="man-pages.html#cb131-1"></a><span class="dt">int</span> s <span class="op">=</span> socket<span class="op">(</span>PF_INET<span class="op">,</span> SOCK_STREAM<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb131-2"><a href="man-pages.html#cb131-2"></a></span>
|
|||
|
|
<span id="cb131-3"><a href="man-pages.html#cb131-3"></a><span class="co">// ...do some send()s and stuff in here...</span></span>
|
|||
|
|
<span id="cb131-4"><a href="man-pages.html#cb131-4"></a></span>
|
|||
|
|
<span id="cb131-5"><a href="man-pages.html#cb131-5"></a><span class="co">// and now that we're done, don't allow any more sends()s:</span></span>
|
|||
|
|
<span id="cb131-6"><a href="man-pages.html#cb131-6"></a>shutdown<span class="op">(</span>s<span class="op">,</span> SHUT_WR<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-20">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#closeman"><code>close()</code></a></p>
|
|||
|
|
<h2 data-number="9.23" id="socketman"><span class="header-section-number">9.23</span> <code>socket()</code></h2>
|
|||
|
|
<p></p>
|
|||
|
|
<p>Allocate a socket descriptor</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-22">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb132"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb132-1"><a href="man-pages.html#cb132-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/types.h></span></span>
|
|||
|
|
<span id="cb132-2"><a href="man-pages.html#cb132-2" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><sys/socket.h></span></span>
|
|||
|
|
<span id="cb132-3"><a href="man-pages.html#cb132-3" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb132-4"><a href="man-pages.html#cb132-4" aria-hidden="true" tabindex="-1"></a><span class="dt">int</span> socket<span class="op">(</span><span class="dt">int</span> domain<span class="op">,</span> <span class="dt">int</span> type<span class="op">,</span> <span class="dt">int</span> protocol<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-22">Description</h3>
|
|||
|
|
<p>Returns a new socket descriptor that you can use to do sockety things with. This is generally the first call in the whopping process of writing a socket program, and you can use the result for subsequent calls to <code>listen()</code>, <code>bind()</code>, <code>accept()</code>, or a variety of other functions.</p>
|
|||
|
|
<p>In usual usage, you get the values for these parameters from a call to <code>getaddrinfo()</code>, as shown in the example below. But you can fill them in by hand if you really want to.</p>
|
|||
|
|
<table>
|
|||
|
|
<colgroup>
|
|||
|
|
<col style="width: 16%" />
|
|||
|
|
<col style="width: 83%" />
|
|||
|
|
</colgroup>
|
|||
|
|
<thead>
|
|||
|
|
<tr class="header">
|
|||
|
|
<th>Parameter</th>
|
|||
|
|
<th>Description</th>
|
|||
|
|
</tr>
|
|||
|
|
</thead>
|
|||
|
|
<tbody>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>domain</code></td>
|
|||
|
|
<td><code>domain</code> describes what kind of socket you’re interested in. This can, believe me, be a wide variety of things, but since this is a socket guide, it’s going to be <code>PF_INET</code> for IPv4, and <code>PF_INET6</code> for IPv6.</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="even">
|
|||
|
|
<td><code>type</code></td>
|
|||
|
|
<td>Also, the <code>type</code> parameter can be a number of things, but you’ll probably be setting it to either <code>SOCK_STREAM</code> for reliable TCP sockets (<code>send()</code>, <code>recv()</code>) or <code>SOCK_DGRAM</code> for unreliable fast UDP sockets (<code>sendto()</code>, <code>recvfrom()</code>). (Another interesting socket type is <code>SOCK_RAW</code> which can be used to construct packets by hand. It’s pretty cool.)</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr class="odd">
|
|||
|
|
<td><code>protocol</code></td>
|
|||
|
|
<td>Finally, the <code>protocol</code> parameter tells which protocol to use with a certain socket type. Like I’ve already said, for instance, <code>SOCK_STREAM</code> uses TCP. Fortunately for you, when using <code>SOCK_STREAM</code> or <code>SOCK_DGRAM</code>, you can just set the protocol to 0, and it’ll use the proper protocol automatically. Otherwise, you can use <code>getprotobyname()</code> to look up the proper protocol number.</td>
|
|||
|
|
</tr>
|
|||
|
|
</tbody>
|
|||
|
|
</table>
|
|||
|
|
<h3 class="unnumbered unlisted" id="return-value-22">Return Value</h3>
|
|||
|
|
<p>The new socket descriptor to be used in subsequent calls, or <code>-1</code> on error (and <code>errno</code> will be set accordingly).</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-22">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb133"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb133-1"><a href="man-pages.html#cb133-1"></a><span class="kw">struct</span> addrinfo hints<span class="op">,</span> <span class="op">*</span>res<span class="op">;</span></span>
|
|||
|
|
<span id="cb133-2"><a href="man-pages.html#cb133-2"></a><span class="dt">int</span> sockfd<span class="op">;</span></span>
|
|||
|
|
<span id="cb133-3"><a href="man-pages.html#cb133-3"></a></span>
|
|||
|
|
<span id="cb133-4"><a href="man-pages.html#cb133-4"></a><span class="co">// first, load up address structs with getaddrinfo():</span></span>
|
|||
|
|
<span id="cb133-5"><a href="man-pages.html#cb133-5"></a></span>
|
|||
|
|
<span id="cb133-6"><a href="man-pages.html#cb133-6"></a>memset<span class="op">(&</span>hints<span class="op">,</span> <span class="dv">0</span><span class="op">,</span> <span class="kw">sizeof</span> hints<span class="op">);</span></span>
|
|||
|
|
<span id="cb133-7"><a href="man-pages.html#cb133-7"></a>hints<span class="op">.</span>ai_family <span class="op">=</span> AF_UNSPEC<span class="op">;</span> <span class="co">// AF_INET, AF_INET6, or AF_UNSPEC</span></span>
|
|||
|
|
<span id="cb133-8"><a href="man-pages.html#cb133-8"></a>hints<span class="op">.</span>ai_socktype <span class="op">=</span> SOCK_STREAM<span class="op">;</span> <span class="co">// SOCK_STREAM or SOCK_DGRAM</span></span>
|
|||
|
|
<span id="cb133-9"><a href="man-pages.html#cb133-9"></a></span>
|
|||
|
|
<span id="cb133-10"><a href="man-pages.html#cb133-10"></a>getaddrinfo<span class="op">(</span><span class="st">"www.example.com"</span><span class="op">,</span> <span class="st">"3490"</span><span class="op">,</span> <span class="op">&</span>hints<span class="op">,</span> <span class="op">&</span>res<span class="op">);</span></span>
|
|||
|
|
<span id="cb133-11"><a href="man-pages.html#cb133-11"></a></span>
|
|||
|
|
<span id="cb133-12"><a href="man-pages.html#cb133-12"></a><span class="co">// make a socket using the information gleaned from getaddrinfo():</span></span>
|
|||
|
|
<span id="cb133-13"><a href="man-pages.html#cb133-13"></a>sockfd <span class="op">=</span> socket<span class="op">(</span>res<span class="op">-></span>ai_family<span class="op">,</span> res<span class="op">-></span>ai_socktype<span class="op">,</span> res<span class="op">-></span>ai_protocol<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-21">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#acceptman"><code>accept()</code></a>, <a href="man-pages.html#bindman"><code>bind()</code></a>, <a href="man-pages.html#getaddrinfoman"><code>getaddrinfo()</code></a>, <a href="man-pages.html#listenman"><code>listen()</code></a></p>
|
|||
|
|
<h2 data-number="9.24" id="structsockaddrman"><span class="header-section-number">9.24</span> <code>struct sockaddr</code> and pals</h2>
|
|||
|
|
<p> </p>
|
|||
|
|
<p>Structures for handling internet addresses</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="synopsis-23">Synopsis</h3>
|
|||
|
|
<div class="sourceCode" id="cb134"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb134-1"><a href="man-pages.html#cb134-1" aria-hidden="true" tabindex="-1"></a><span class="pp">#include </span><span class="im"><netinet/in.h></span></span>
|
|||
|
|
<span id="cb134-2"><a href="man-pages.html#cb134-2" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb134-3"><a href="man-pages.html#cb134-3" aria-hidden="true" tabindex="-1"></a><span class="co">// All pointers to socket address structures are often cast to pointers</span></span>
|
|||
|
|
<span id="cb134-4"><a href="man-pages.html#cb134-4" aria-hidden="true" tabindex="-1"></a><span class="co">// to this type before use in various functions and system calls:</span></span>
|
|||
|
|
<span id="cb134-5"><a href="man-pages.html#cb134-5" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb134-6"><a href="man-pages.html#cb134-6" aria-hidden="true" tabindex="-1"></a><span class="kw">struct</span> sockaddr <span class="op">{</span></span>
|
|||
|
|
<span id="cb134-7"><a href="man-pages.html#cb134-7" aria-hidden="true" tabindex="-1"></a> <span class="dt">unsigned</span> <span class="dt">short</span> sa_family<span class="op">;</span> <span class="co">// address family, AF_xxx</span></span>
|
|||
|
|
<span id="cb134-8"><a href="man-pages.html#cb134-8" aria-hidden="true" tabindex="-1"></a> <span class="dt">char</span> sa_data<span class="op">[</span><span class="dv">14</span><span class="op">];</span> <span class="co">// 14 bytes of protocol address</span></span>
|
|||
|
|
<span id="cb134-9"><a href="man-pages.html#cb134-9" aria-hidden="true" tabindex="-1"></a><span class="op">};</span></span>
|
|||
|
|
<span id="cb134-10"><a href="man-pages.html#cb134-10" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb134-11"><a href="man-pages.html#cb134-11" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb134-12"><a href="man-pages.html#cb134-12" aria-hidden="true" tabindex="-1"></a><span class="co">// IPv4 AF_INET sockets:</span></span>
|
|||
|
|
<span id="cb134-13"><a href="man-pages.html#cb134-13" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb134-14"><a href="man-pages.html#cb134-14" aria-hidden="true" tabindex="-1"></a><span class="kw">struct</span> sockaddr_in <span class="op">{</span></span>
|
|||
|
|
<span id="cb134-15"><a href="man-pages.html#cb134-15" aria-hidden="true" tabindex="-1"></a> <span class="dt">short</span> sin_family<span class="op">;</span> <span class="co">// e.g. AF_INET, AF_INET6</span></span>
|
|||
|
|
<span id="cb134-16"><a href="man-pages.html#cb134-16" aria-hidden="true" tabindex="-1"></a> <span class="dt">unsigned</span> <span class="dt">short</span> sin_port<span class="op">;</span> <span class="co">// e.g. htons(3490)</span></span>
|
|||
|
|
<span id="cb134-17"><a href="man-pages.html#cb134-17" aria-hidden="true" tabindex="-1"></a> <span class="kw">struct</span> in_addr sin_addr<span class="op">;</span> <span class="co">// see struct in_addr, below</span></span>
|
|||
|
|
<span id="cb134-18"><a href="man-pages.html#cb134-18" aria-hidden="true" tabindex="-1"></a> <span class="dt">char</span> sin_zero<span class="op">[</span><span class="dv">8</span><span class="op">];</span> <span class="co">// zero this if you want to</span></span>
|
|||
|
|
<span id="cb134-19"><a href="man-pages.html#cb134-19" aria-hidden="true" tabindex="-1"></a><span class="op">};</span></span>
|
|||
|
|
<span id="cb134-20"><a href="man-pages.html#cb134-20" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb134-21"><a href="man-pages.html#cb134-21" aria-hidden="true" tabindex="-1"></a><span class="kw">struct</span> in_addr <span class="op">{</span></span>
|
|||
|
|
<span id="cb134-22"><a href="man-pages.html#cb134-22" aria-hidden="true" tabindex="-1"></a> <span class="dt">unsigned</span> <span class="dt">long</span> s_addr<span class="op">;</span> <span class="co">// load with inet_pton()</span></span>
|
|||
|
|
<span id="cb134-23"><a href="man-pages.html#cb134-23" aria-hidden="true" tabindex="-1"></a><span class="op">};</span></span>
|
|||
|
|
<span id="cb134-24"><a href="man-pages.html#cb134-24" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb134-25"><a href="man-pages.html#cb134-25" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb134-26"><a href="man-pages.html#cb134-26" aria-hidden="true" tabindex="-1"></a><span class="co">// IPv6 AF_INET6 sockets:</span></span>
|
|||
|
|
<span id="cb134-27"><a href="man-pages.html#cb134-27" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb134-28"><a href="man-pages.html#cb134-28" aria-hidden="true" tabindex="-1"></a><span class="kw">struct</span> sockaddr_in6 <span class="op">{</span></span>
|
|||
|
|
<span id="cb134-29"><a href="man-pages.html#cb134-29" aria-hidden="true" tabindex="-1"></a> u_int16_t sin6_family<span class="op">;</span> <span class="co">// address family, AF_INET6</span></span>
|
|||
|
|
<span id="cb134-30"><a href="man-pages.html#cb134-30" aria-hidden="true" tabindex="-1"></a> u_int16_t sin6_port<span class="op">;</span> <span class="co">// port number, Network Byte Order</span></span>
|
|||
|
|
<span id="cb134-31"><a href="man-pages.html#cb134-31" aria-hidden="true" tabindex="-1"></a> u_int32_t sin6_flowinfo<span class="op">;</span> <span class="co">// IPv6 flow information</span></span>
|
|||
|
|
<span id="cb134-32"><a href="man-pages.html#cb134-32" aria-hidden="true" tabindex="-1"></a> <span class="kw">struct</span> in6_addr sin6_addr<span class="op">;</span> <span class="co">// IPv6 address</span></span>
|
|||
|
|
<span id="cb134-33"><a href="man-pages.html#cb134-33" aria-hidden="true" tabindex="-1"></a> u_int32_t sin6_scope_id<span class="op">;</span> <span class="co">// Scope ID</span></span>
|
|||
|
|
<span id="cb134-34"><a href="man-pages.html#cb134-34" aria-hidden="true" tabindex="-1"></a><span class="op">};</span></span>
|
|||
|
|
<span id="cb134-35"><a href="man-pages.html#cb134-35" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb134-36"><a href="man-pages.html#cb134-36" aria-hidden="true" tabindex="-1"></a><span class="kw">struct</span> in6_addr <span class="op">{</span></span>
|
|||
|
|
<span id="cb134-37"><a href="man-pages.html#cb134-37" aria-hidden="true" tabindex="-1"></a> <span class="dt">unsigned</span> <span class="dt">char</span> s6_addr<span class="op">[</span><span class="dv">16</span><span class="op">];</span> <span class="co">// load with inet_pton()</span></span>
|
|||
|
|
<span id="cb134-38"><a href="man-pages.html#cb134-38" aria-hidden="true" tabindex="-1"></a><span class="op">};</span></span>
|
|||
|
|
<span id="cb134-39"><a href="man-pages.html#cb134-39" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb134-40"><a href="man-pages.html#cb134-40" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb134-41"><a href="man-pages.html#cb134-41" aria-hidden="true" tabindex="-1"></a><span class="co">// General socket address holding structure, big enough to hold either</span></span>
|
|||
|
|
<span id="cb134-42"><a href="man-pages.html#cb134-42" aria-hidden="true" tabindex="-1"></a><span class="co">// struct sockaddr_in or struct sockaddr_in6 data:</span></span>
|
|||
|
|
<span id="cb134-43"><a href="man-pages.html#cb134-43" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb134-44"><a href="man-pages.html#cb134-44" aria-hidden="true" tabindex="-1"></a><span class="kw">struct</span> sockaddr_storage <span class="op">{</span></span>
|
|||
|
|
<span id="cb134-45"><a href="man-pages.html#cb134-45" aria-hidden="true" tabindex="-1"></a> sa_family_t ss_family<span class="op">;</span> <span class="co">// address family</span></span>
|
|||
|
|
<span id="cb134-46"><a href="man-pages.html#cb134-46" aria-hidden="true" tabindex="-1"></a></span>
|
|||
|
|
<span id="cb134-47"><a href="man-pages.html#cb134-47" aria-hidden="true" tabindex="-1"></a> <span class="co">// all this is padding, implementation specific, ignore it:</span></span>
|
|||
|
|
<span id="cb134-48"><a href="man-pages.html#cb134-48" aria-hidden="true" tabindex="-1"></a> <span class="dt">char</span> __ss_pad1<span class="op">[</span>_SS_PAD1SIZE<span class="op">];</span></span>
|
|||
|
|
<span id="cb134-49"><a href="man-pages.html#cb134-49" aria-hidden="true" tabindex="-1"></a> <span class="dt">int64_t</span> __ss_align<span class="op">;</span></span>
|
|||
|
|
<span id="cb134-50"><a href="man-pages.html#cb134-50" aria-hidden="true" tabindex="-1"></a> <span class="dt">char</span> __ss_pad2<span class="op">[</span>_SS_PAD2SIZE<span class="op">];</span></span>
|
|||
|
|
<span id="cb134-51"><a href="man-pages.html#cb134-51" aria-hidden="true" tabindex="-1"></a><span class="op">};</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="description-23">Description</h3>
|
|||
|
|
<p>These are the basic structures for all syscalls and functions that deal with internet addresses. Often you’ll use <code>getaddrinfo()</code> to fill these structures out, and then will read them when you have to.</p>
|
|||
|
|
<p>In memory, the <code>struct sockaddr_in</code> and <code>struct sockaddr_in6</code> share the same beginning structure as <code>struct sockaddr</code>, and you can freely cast the pointer of one type to the other without any harm, except the possible end of the universe.</p>
|
|||
|
|
<p>Just kidding on that end-of-the-universe thing…if the universe does end when you cast a <code>struct sockaddr_in*</code> to a <code>struct sockaddr*</code>, I promise you it’s pure coincidence and you shouldn’t even worry about it.</p>
|
|||
|
|
<p>So, with that in mind, remember that whenever a function says it takes a <code>struct sockaddr*</code> you can cast your <code>struct sockaddr_in*</code>, <code>struct sockaddr_in6*</code>, or <code>struct sockadd_storage*</code> to that type with ease and safety.</p>
|
|||
|
|
<p><code>struct sockaddr_in</code> is the structure used with IPv4 addresses (e.g. “192.0.2.10”). It holds an address family (<code>AF_INET</code>), a port in <code>sin_port</code>, and an IPv4 address in <code>sin_addr</code>.</p>
|
|||
|
|
<p>There’s also this <code>sin_zero</code> field in <code>struct sockaddr_in</code> which some people claim must be set to zero. Other people don’t claim anything about it (the Linux documentation doesn’t even mention it at all), and setting it to zero doesn’t seem to be actually necessary. So, if you feel like it, set it to zero using <code>memset()</code>.</p>
|
|||
|
|
<p>Now, that <code>struct in_addr</code> is a weird beast on different systems. Sometimes it’s a crazy <code>union</code> with all kinds of <code>#define</code>s and other nonsense. But what you should do is only use the <code>s_addr</code> field in this structure, because many systems only implement that one.</p>
|
|||
|
|
<p><code>struct sockadd_in6</code> and <code>struct in6_addr</code> are very similar, except they’re used for IPv6.</p>
|
|||
|
|
<p><code>struct sockaddr_storage</code> is a struct you can pass to <code>accept()</code> or <code>recvfrom()</code> when you’re trying to write IP version-agnostic code and you don’t know if the new address is going to be IPv4 or IPv6. The <code>struct sockaddr_storage</code> structure is large enough to hold both types, unlike the original small <code>struct sockaddr</code>.</p>
|
|||
|
|
<h3 class="unnumbered unlisted" id="example-23">Example</h3>
|
|||
|
|
<div class="sourceCode" id="cb135"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb135-1"><a href="man-pages.html#cb135-1"></a><span class="co">// IPv4:</span></span>
|
|||
|
|
<span id="cb135-2"><a href="man-pages.html#cb135-2"></a></span>
|
|||
|
|
<span id="cb135-3"><a href="man-pages.html#cb135-3"></a><span class="kw">struct</span> sockaddr_in ip4addr<span class="op">;</span></span>
|
|||
|
|
<span id="cb135-4"><a href="man-pages.html#cb135-4"></a><span class="dt">int</span> s<span class="op">;</span></span>
|
|||
|
|
<span id="cb135-5"><a href="man-pages.html#cb135-5"></a></span>
|
|||
|
|
<span id="cb135-6"><a href="man-pages.html#cb135-6"></a>ip4addr<span class="op">.</span>sin_family <span class="op">=</span> AF_INET<span class="op">;</span></span>
|
|||
|
|
<span id="cb135-7"><a href="man-pages.html#cb135-7"></a>ip4addr<span class="op">.</span>sin_port <span class="op">=</span> htons<span class="op">(</span><span class="dv">3490</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb135-8"><a href="man-pages.html#cb135-8"></a>inet_pton<span class="op">(</span>AF_INET<span class="op">,</span> <span class="st">"10.0.0.1"</span><span class="op">,</span> <span class="op">&</span>ip4addr<span class="op">.</span>sin_addr<span class="op">);</span></span>
|
|||
|
|
<span id="cb135-9"><a href="man-pages.html#cb135-9"></a></span>
|
|||
|
|
<span id="cb135-10"><a href="man-pages.html#cb135-10"></a>s <span class="op">=</span> socket<span class="op">(</span>PF_INET<span class="op">,</span> SOCK_STREAM<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb135-11"><a href="man-pages.html#cb135-11"></a>bind<span class="op">(</span>s<span class="op">,</span> <span class="op">(</span><span class="kw">struct</span> sockaddr<span class="op">*)&</span>ip4addr<span class="op">,</span> <span class="kw">sizeof</span> ip4addr<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<div class="sourceCode" id="cb136"><pre class="sourceCode numberSource c numberLines"><code class="sourceCode c"><span id="cb136-1"><a href="man-pages.html#cb136-1"></a><span class="co">// IPv6:</span></span>
|
|||
|
|
<span id="cb136-2"><a href="man-pages.html#cb136-2"></a></span>
|
|||
|
|
<span id="cb136-3"><a href="man-pages.html#cb136-3"></a><span class="kw">struct</span> sockaddr_in6 ip6addr<span class="op">;</span></span>
|
|||
|
|
<span id="cb136-4"><a href="man-pages.html#cb136-4"></a><span class="dt">int</span> s<span class="op">;</span></span>
|
|||
|
|
<span id="cb136-5"><a href="man-pages.html#cb136-5"></a></span>
|
|||
|
|
<span id="cb136-6"><a href="man-pages.html#cb136-6"></a>ip6addr<span class="op">.</span>sin6_family <span class="op">=</span> AF_INET6<span class="op">;</span></span>
|
|||
|
|
<span id="cb136-7"><a href="man-pages.html#cb136-7"></a>ip6addr<span class="op">.</span>sin6_port <span class="op">=</span> htons<span class="op">(</span><span class="dv">4950</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb136-8"><a href="man-pages.html#cb136-8"></a>inet_pton<span class="op">(</span>AF_INET6<span class="op">,</span> <span class="st">"2001:db8:8714:3a90::12"</span><span class="op">,</span> <span class="op">&</span>ip6addr<span class="op">.</span>sin6_addr<span class="op">);</span></span>
|
|||
|
|
<span id="cb136-9"><a href="man-pages.html#cb136-9"></a></span>
|
|||
|
|
<span id="cb136-10"><a href="man-pages.html#cb136-10"></a>s <span class="op">=</span> socket<span class="op">(</span>PF_INET6<span class="op">,</span> SOCK_STREAM<span class="op">,</span> <span class="dv">0</span><span class="op">);</span></span>
|
|||
|
|
<span id="cb136-11"><a href="man-pages.html#cb136-11"></a>bind<span class="op">(</span>s<span class="op">,</span> <span class="op">(</span><span class="kw">struct</span> sockaddr<span class="op">*)&</span>ip6addr<span class="op">,</span> <span class="kw">sizeof</span> ip6addr<span class="op">);</span></span></code></pre></div>
|
|||
|
|
<h3 class="unnumbered unlisted" id="see-also-22">See Also</h3>
|
|||
|
|
<p><a href="man-pages.html#acceptman"><code>accept()</code></a>, <a href="man-pages.html#bindman"><code>bind()</code></a>, <a href="man-pages.html#connectman"><code>connect()</code></a>, <a href="man-pages.html#inet_ntoaman"><code>inet_aton()</code></a>, <a href="man-pages.html#inet_ntoaman"><code>inet_ntoa()</code></a></p>
|
|||
|
|
<hr><div style="text-align:center"><span><a href="common-questions.html">Prev</a> | </span><a href="index.html">Contents</a><span> | <a href="more-references.html">Next</a></span></div></body>
|
|||
|
|
</html>
|