Commit | Line | Data |
---|---|---|
da268306 KB |
1 | .\" Copyright (c) 1983 The Regents of the University of California. |
2 | .\" All rights reserved. | |
39582001 | 3 | .\" |
da268306 KB |
4 | .\" Redistribution and use in source and binary forms are permitted |
5 | .\" provided that the above copyright notice and this paragraph are | |
6 | .\" duplicated in all such forms and that any documentation, | |
7 | .\" advertising materials, and other materials related to such | |
8 | .\" distribution and use acknowledge that the software was developed | |
9 | .\" by the University of California, Berkeley. The name of the | |
10 | .\" University may not be used to endorse or promote products derived | |
11 | .\" from this software without specific prior written permission. | |
12 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR | |
13 | .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED | |
14 | .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. | |
15 | .\" | |
16 | .\" @(#)socket.2 6.6 (Berkeley) %G% | |
39582001 | 17 | .\" |
af71be09 | 18 | .TH SOCKET 2 "" |
39582001 KM |
19 | .UC 5 |
20 | .SH NAME | |
21 | socket \- create an endpoint for communication | |
22 | .SH SYNOPSIS | |
23 | .nf | |
24 | .ft B | |
25 | #include <sys/types.h> | |
26 | #include <sys/socket.h> | |
27 | .PP | |
28 | .ft B | |
d25f1c67 MK |
29 | s = socket(domain, type, protocol) |
30 | int s, domain, type, protocol; | |
39582001 KM |
31 | .fi |
32 | .SH DESCRIPTION | |
33 | .I Socket | |
34 | creates an endpoint for communication and returns a descriptor. | |
35 | .PP | |
36 | The | |
d25f1c67 MK |
37 | .I domain |
38 | parameter specifies a communications domain within which | |
39 | communication will take place; this selects the protocol family | |
40 | which should be used. | |
41 | The protocol family generally is the same as the address family | |
42 | for the addresses supplied in later operations on the socket. | |
43 | These families are defined in the include file | |
39582001 KM |
44 | .IR <sys/socket.h> . |
45 | The currently understood formats are | |
46 | .PP | |
47 | .RS | |
48 | .nf | |
49 | .ta 1.25i 1.75i | |
d25f1c67 MK |
50 | PF_UNIX (UNIX internal protocols), |
51 | PF_INET (ARPA Internet protocols), | |
52 | PF_NS (Xerox Network Systems protocols), and | |
53 | PF_IMPLINK (IMP \*(lqhost at IMP\*(rq link layer). | |
39582001 KM |
54 | .fi |
55 | .RE | |
56 | .PP | |
57 | The socket has the indicated | |
eff6446c | 58 | .I type, |
39582001 KM |
59 | which specifies the semantics of communication. Currently |
60 | defined types are: | |
61 | .PP | |
62 | .RS | |
63 | .nf | |
64 | SOCK_STREAM | |
65 | SOCK_DGRAM | |
66 | SOCK_RAW | |
67 | SOCK_SEQPACKET | |
68 | SOCK_RDM | |
69 | .fi | |
70 | .RE | |
71 | .PP | |
72 | A SOCK_STREAM type provides sequenced, reliable, | |
d25f1c67 MK |
73 | two-way connection based byte streams. |
74 | An out-of-band data transmission mechanism may be supported. | |
39582001 KM |
75 | A SOCK_DGRAM socket supports |
76 | datagrams (connectionless, unreliable messages of | |
77 | a fixed (typically small) maximum length). | |
cab13e85 KM |
78 | A SOCK_SEQPACKET socket may provide a sequenced, reliable, |
79 | two-way connection-based data transmission path for datagrams | |
80 | of fixed maximum length; a consumer may be required to read | |
81 | an entire packet with each read system call. | |
82 | This facility is protocol specific, and presently implemented | |
d25f1c67 MK |
83 | only for PF_NS. |
84 | SOCK_RAW sockets provide access to internal network protocols and interfaces. | |
39582001 KM |
85 | The types SOCK_RAW, |
86 | which is available only to the super-user, and | |
cab13e85 | 87 | SOCK_RDM, which is planned, |
39582001 KM |
88 | but not yet implemented, are not described here. |
89 | .PP | |
90 | The | |
91 | .I protocol | |
92 | specifies a particular protocol to be used with the socket. | |
93 | Normally only a single protocol exists to support a particular | |
d25f1c67 MK |
94 | socket type within a given protocol family. However, it is possible |
95 | that many protocols may exist, in which case a particular protocol | |
39582001 KM |
96 | must be specified in this manner. The protocol number to use is |
97 | particular to the \*(lqcommunication domain\*(rq in which communication | |
98 | is to take place; see | |
39582001 KM |
99 | .IR protocols (3N). |
100 | .PP | |
101 | Sockets of type SOCK_STREAM | |
102 | are full-duplex byte streams, similar | |
103 | to pipes. A stream socket must be in a | |
104 | .I connected | |
105 | state before any data may be sent or received | |
106 | on it. A connection to another socket is created with a | |
107 | .IR connect (2) | |
108 | call. Once connected, data may be transferred using | |
109 | .IR read (2) | |
110 | and | |
111 | .IR write (2) | |
112 | calls or some variant of the | |
113 | .IR send (2) | |
114 | and | |
115 | .IR recv (2) | |
116 | calls. When a session has been completed a | |
117 | .IR close (2) | |
118 | may be performed. | |
119 | Out-of-band data may also be transmitted as described in | |
120 | .IR send (2) | |
121 | and received as described in | |
122 | .IR recv (2). | |
123 | .PP | |
124 | The communications protocols used to implement a | |
125 | SOCK_STREAM insure that data | |
126 | is not lost or duplicated. If a piece of data for which the | |
127 | peer protocol has buffer space cannot be successfully transmitted | |
128 | within a reasonable length of time, then | |
129 | the connection is considered broken and calls | |
130 | will indicate an error with | |
131 | \-1 returns and with ETIMEDOUT as the specific code | |
132 | in the global variable errno. | |
133 | The protocols optionally keep sockets \*(lqwarm\*(rq by | |
134 | forcing transmissions | |
135 | roughly every minute in the absence of other activity. | |
136 | An error is then indicated if no response can be | |
137 | elicited on an otherwise | |
138 | idle connection for a extended period (e.g. 5 minutes). | |
139 | A SIGPIPE signal is raised if a process sends | |
140 | on a broken stream; this causes naive processes, | |
141 | which do not handle the signal, to exit. | |
142 | .PP | |
cab13e85 KM |
143 | SOCK_SEQPACKET sockets employ the same system calls |
144 | as SOCK_STREAM sockets. The only difference | |
145 | is that | |
146 | .IR read (2) | |
147 | calls will return only the amount of data requested, | |
148 | and any remaining in the arriving packet will be discarded. | |
149 | .PP | |
39582001 KM |
150 | SOCK_DGRAM and SOCK_RAW |
151 | sockets allow sending of datagrams to correspondents | |
152 | named in | |
153 | .IR send (2) | |
d25f1c67 MK |
154 | calls. Datagrams are generally received with |
155 | .IR recvfrom (2), | |
156 | which returns the next datagram with its return address. | |
39582001 KM |
157 | .PP |
158 | An | |
159 | .IR fcntl (2) | |
160 | call can be used to specify a process group to receive | |
161 | a SIGURG signal when the out-of-band data arrives. | |
d25f1c67 MK |
162 | It may also enable non-blocking I/O |
163 | and asynchronous notification of I/O events | |
164 | via SIGIO. | |
39582001 KM |
165 | .PP |
166 | The operation of sockets is controlled by socket level | |
167 | .IR options . | |
168 | These options are defined in the file | |
d25f1c67 MK |
169 | .RI < sys/socket.h >. |
170 | .IR Setsockopt (2) | |
39582001 KM |
171 | and |
172 | .IR getsockopt (2) | |
173 | are used to set and get options, respectively. | |
39582001 KM |
174 | .SH "RETURN VALUE |
175 | A \-1 is returned if an error occurs, otherwise the return | |
176 | value is a descriptor referencing the socket. | |
177 | .SH "ERRORS | |
178 | The \fIsocket\fP call fails if: | |
179 | .TP 20 | |
39582001 | 180 | [EPROTONOSUPPORT] |
d25f1c67 MK |
181 | The protocol type or the specified protocol is not supported |
182 | within this domain. | |
39582001 KM |
183 | .TP 20 |
184 | [EMFILE] | |
185 | The per-process descriptor table is full. | |
186 | .TP 20 | |
d25f1c67 MK |
187 | [ENFILE] |
188 | The system file table is full. | |
189 | .TP 20 | |
190 | [EACCESS] | |
191 | Permission to create a socket of the specified type and/or protocol | |
192 | is denied. | |
193 | .TP 20 | |
39582001 | 194 | [ENOBUFS] |
d25f1c67 MK |
195 | Insufficient buffer space is available. |
196 | The socket cannot be created until sufficient resources are freed. | |
39582001 KM |
197 | .SH SEE ALSO |
198 | accept(2), bind(2), connect(2), getsockname(2), getsockopt(2), | |
d25f1c67 MK |
199 | ioctl(2), listen(2), read(2), recv(2), |
200 | select(2), send(2), shutdown(2), socketpair(2), write(2) | |
39582001 | 201 | .br |
cb9fed07 KD |
202 | ``An Introductory 4.3BSD Interprocess Communication Tutorial.'' |
203 | (reprinted in UNIX Programmer's Supplementary Documents Volume 1, PS1:7) | |
d25f1c67 | 204 | ``An Advanced 4.3BSD Interprocess Communication Tutorial.'' |
cb9fed07 | 205 | (reprinted in UNIX Programmer's Supplementary Documents Volume 1, PS1:8) |