1 .\" $NetBSD: ip.4,v 1.3 1994/11/30 16:22:19 jtc Exp $
3 .\" Copyright (c) 1983, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. All advertising materials mentioning features or use of this software
15 .\" must display the following acknowledgement:
16 .\" This product includes software developed by the University of
17 .\" California, Berkeley and its contributors.
18 .\" 4. Neither the name of the University nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\" @(#)ip.4 8.2 (Berkeley) 11/30/93
43 .Fd #include <sys/socket.h>
44 .Fd #include <netinet/in.h>
46 .Fn socket AF_INET SOCK_RAW proto
49 is the transport layer protocol used
50 by the Internet protocol family.
51 Options may be set at the
54 when using higher-level protocols that are based on
60 It may also be accessed
63 when developing new protocols, or
64 special-purpose applications.
72 may be used to provide
74 options to be transmitted in the
76 header of each outgoing packet
77 or to examine the header options on incoming packets.
79 options may be used with any socket type in the Internet family.
82 options to be sent is that specified by the
84 protocol specification (RFC-791), with one exception:
85 the list of addresses for Source Route options must include the first-hop
86 gateway at the beginning of the list of gateways.
87 The first-hop gateway address will be extracted from the option list
88 and the size adjusted accordingly before use.
89 To disable previously specified options,
90 use a zero-length buffer:
92 setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0);
98 may be used to set the type-of-service and time-to-live
105 sockets. For example,
107 int tos = IPTOS_LOWDELAY; /* see <netinet/in.h> */
108 setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos));
110 int ttl = 60; /* max = 255 */
111 setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl));
116 option is enabled on a
121 call will return the destination
126 The msg_control field in the msghdr structure points to a buffer
127 that contains a cmsghdr structure followed by the
130 The cmsghdr fields have the following values:
132 cmsg_len = CMSG_LEN(sizeof(struct in_addr))
133 cmsg_level = IPPROTO_IP
134 cmsg_type = IP_RECVDSTADDR
139 option is enabled on a
146 call will return the TOS (type of service) field of the IP header.
147 The msg_control field in the msghdr structure points to a buffer
148 that contains a cmsghdr structure followed by the TOS.
149 The cmsghdr fields have the following values:
151 cmsg_len = CMSG_LEN(sizeof(u_char))
152 cmsg_level = IPPROTO_IP
153 cmsg_type = IP_RECVTOS
155 .Ss "Multicast Options"
158 multicasting is supported only on
164 and only on networks where the interface
165 driver supports multicasting.
169 option changes the time-to-live (TTL)
170 for outgoing multicast datagrams
171 in order to control the scope of the multicasts:
173 u_char ttl; /* range: 0 to 255, default = 1 */
174 setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl));
177 Datagrams with a TTL of 1 are not forwarded beyond the local network.
178 Multicast datagrams with a TTL of 0 will not be transmitted on any network,
179 but may be delivered locally if the sending host belongs to the destination
180 group and if multicast loopback has not been disabled on the sending socket
181 (see below). Multicast datagrams with TTL greater than 1 may be forwarded
182 to other networks if a multicast router is attached to the local network.
184 For hosts with multiple interfaces, each multicast transmission is
185 sent from the primary network interface.
188 option overrides the default for
189 subsequent transmissions from a given socket:
192 setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr));
195 where "addr" is the local
197 address of the desired interface or
199 to specify the default interface.
200 An interface's local IP address and multicast capability can
206 Normal applications should not need to use this option.
208 If a multicast datagram is sent to a group to which the sending host itself
209 belongs (on the outgoing interface), a copy of the datagram is, by default,
210 looped back by the IP layer for local delivery.
212 .Dv IP_MULTICAST_LOOP
213 option gives the sender explicit control
214 over whether or not subsequent datagrams are looped back:
216 u_char loop; /* 0 = disable, 1 = enable (default) */
217 setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop));
221 improves performance for applications that may have no more than one
222 instance on a single host (such as a router demon), by eliminating
223 the overhead of receiving their own transmissions. It should generally not
224 be used by applications for which there may be more than one instance on a
225 single host (such as a conferencing program) or for which the sender does
226 not belong to the destination group (such as a time querying program).
228 A multicast datagram sent with an initial TTL greater than 1 may be delivered
229 to the sending host on a different interface from that on which it was sent,
230 if the host belongs to the destination group on that other interface. The
231 loopback control option has no effect on such delivery.
233 A host must become a member of a multicast group before it can receive
234 datagrams sent to the group. To join a multicast group, use the
235 .Dv IP_ADD_MEMBERSHIP
239 setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq));
244 is the following structure:
247 struct in_addr imr_multiaddr; /* multicast group to join */
248 struct in_addr imr_interface; /* interface to join on */
256 to choose the default multicast interface,
259 address of a particular multicast-capable interface if
260 the host is multihomed.
261 Membership is associated with a single interface;
262 programs running on multihomed hosts may need to
263 join the same group on more than one interface.
265 .Dv IP_MAX_MEMBERSHIPS
266 (currently 20) memberships may be added on a
269 To drop a membership, use:
272 setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq));
277 contains the same values as used to add the membership.
278 Memberships are dropped when the socket is closed or the process exits.
279 .\"-----------------------
284 sockets are connectionless,
285 and are normally used with the
291 call may also be used to fix the destination for future
292 packets (in which case the
300 system calls may be used).
304 is 0, the default protocol
307 packets, and only incoming packets destined for that protocol
311 is non-zero, that protocol number will be used on outgoing packets
312 and to filter incoming packets.
314 Outgoing packets automatically have an
317 them (based on the destination address and the protocol
318 number the socket is created with),
322 Incoming packets are received with
324 header and options intact.
327 indicates the complete IP header is included with the data
328 and may be used only with the
332 #include <netinet/ip.h>
334 int hincl = 1; /* 1 = on, 0 = off */
335 setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl));
340 releases, the program must set all
341 the fields of the IP header, including the following:
343 ip->ip_v = IPVERSION;
344 ip->ip_hl = hlen >> 2;
345 ip->ip_id = 0; /* 0 means kernel set appropriate value */
352 the ip_off and ip_len fields are in host byte order.
354 If the header source address is set to
356 the kernel will choose an appropriate address.
358 A socket operation may fail with one of the following errors returned:
359 .Bl -tag -width [EADDRNOTAVAIL]
361 when trying to establish a connection on a socket which
362 already has one, or when trying to send a datagram with the destination
363 address specified and the socket is already connected;
365 when trying to send a datagram, but
366 no destination address is specified, and the socket hasn't been
369 when the system runs out of memory for
370 an internal data structure;
371 .It Bq Er EADDRNOTAVAIL
372 when an attempt is made to create a
373 socket with a network address for which no network interface
376 when an attempt is made to create
377 a raw IP socket by a non-privileged process.
380 The following errors specific to
382 may occur when setting or getting
385 .Bl -tag -width EADDRNOTAVAILxx
387 An unknown socket option name was given.
389 The IP option field was improperly formed;
390 an option field was shorter than the minimum value
391 or longer than the option buffer provided.
projects / apple / xnu.git / blob