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