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