xref: /freebsd/lib/libsys/connect.2 (revision 8269e7673cf033aba67dab8264fe719920c70f87)
1*8269e767SBrooks Davis.\" Copyright (c) 1983, 1993
2*8269e767SBrooks Davis.\"	The Regents of the University of California.  All rights reserved.
3*8269e767SBrooks Davis.\"
4*8269e767SBrooks Davis.\" Redistribution and use in source and binary forms, with or without
5*8269e767SBrooks Davis.\" modification, are permitted provided that the following conditions
6*8269e767SBrooks Davis.\" are met:
7*8269e767SBrooks Davis.\" 1. Redistributions of source code must retain the above copyright
8*8269e767SBrooks Davis.\"    notice, this list of conditions and the following disclaimer.
9*8269e767SBrooks Davis.\" 2. Redistributions in binary form must reproduce the above copyright
10*8269e767SBrooks Davis.\"    notice, this list of conditions and the following disclaimer in the
11*8269e767SBrooks Davis.\"    documentation and/or other materials provided with the distribution.
12*8269e767SBrooks Davis.\" 3. Neither the name of the University nor the names of its contributors
13*8269e767SBrooks Davis.\"    may be used to endorse or promote products derived from this software
14*8269e767SBrooks Davis.\"    without specific prior written permission.
15*8269e767SBrooks Davis.\"
16*8269e767SBrooks Davis.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17*8269e767SBrooks Davis.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18*8269e767SBrooks Davis.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19*8269e767SBrooks Davis.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20*8269e767SBrooks Davis.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21*8269e767SBrooks Davis.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22*8269e767SBrooks Davis.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23*8269e767SBrooks Davis.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24*8269e767SBrooks Davis.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25*8269e767SBrooks Davis.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26*8269e767SBrooks Davis.\" SUCH DAMAGE.
27*8269e767SBrooks Davis.\"
28*8269e767SBrooks Davis.Dd August 18, 2016
29*8269e767SBrooks Davis.Dt CONNECT 2
30*8269e767SBrooks Davis.Os
31*8269e767SBrooks Davis.Sh NAME
32*8269e767SBrooks Davis.Nm connect
33*8269e767SBrooks Davis.Nd initiate a connection on a socket
34*8269e767SBrooks Davis.Sh LIBRARY
35*8269e767SBrooks Davis.Lb libc
36*8269e767SBrooks Davis.Sh SYNOPSIS
37*8269e767SBrooks Davis.In sys/socket.h
38*8269e767SBrooks Davis.Ft int
39*8269e767SBrooks Davis.Fn connect "int s" "const struct sockaddr *name" "socklen_t namelen"
40*8269e767SBrooks Davis.Sh DESCRIPTION
41*8269e767SBrooks DavisThe
42*8269e767SBrooks Davis.Fa s
43*8269e767SBrooks Davisargument
44*8269e767SBrooks Davisis a socket.
45*8269e767SBrooks DavisIf it is of type
46*8269e767SBrooks Davis.Dv SOCK_DGRAM ,
47*8269e767SBrooks Davisthis call specifies the peer with which the socket is to be associated;
48*8269e767SBrooks Davisthis address is that to which datagrams are to be sent,
49*8269e767SBrooks Davisand the only address from which datagrams are to be received.
50*8269e767SBrooks DavisIf the socket is of type
51*8269e767SBrooks Davis.Dv SOCK_STREAM ,
52*8269e767SBrooks Davisthis call attempts to make a connection to
53*8269e767SBrooks Davisanother socket.
54*8269e767SBrooks DavisThe other socket is specified by
55*8269e767SBrooks Davis.Fa name ,
56*8269e767SBrooks Daviswhich is an address in the communications space of the socket.
57*8269e767SBrooks Davis.Fa namelen
58*8269e767SBrooks Davisindicates the amount of space pointed to by
59*8269e767SBrooks Davis.Fa name ,
60*8269e767SBrooks Davisin bytes; the
61*8269e767SBrooks Davis.Fa sa_len
62*8269e767SBrooks Davismember of
63*8269e767SBrooks Davis.Fa name
64*8269e767SBrooks Davisis ignored.
65*8269e767SBrooks DavisEach communications space interprets the
66*8269e767SBrooks Davis.Fa name
67*8269e767SBrooks Davisargument in its own way.
68*8269e767SBrooks DavisGenerally, stream sockets may successfully
69*8269e767SBrooks Davis.Fn connect
70*8269e767SBrooks Davisonly once; datagram sockets may use
71*8269e767SBrooks Davis.Fn connect
72*8269e767SBrooks Davismultiple times to change their association.
73*8269e767SBrooks DavisDatagram sockets may dissolve the association
74*8269e767SBrooks Davisby connecting to an invalid address, such as a null address.
75*8269e767SBrooks Davis.Sh RETURN VALUES
76*8269e767SBrooks Davis.Rv -std connect
77*8269e767SBrooks Davis.Sh ERRORS
78*8269e767SBrooks DavisThe
79*8269e767SBrooks Davis.Fn connect
80*8269e767SBrooks Davissystem call fails if:
81*8269e767SBrooks Davis.Bl -tag -width Er
82*8269e767SBrooks Davis.It Bq Er EBADF
83*8269e767SBrooks DavisThe
84*8269e767SBrooks Davis.Fa s
85*8269e767SBrooks Davisargument
86*8269e767SBrooks Davisis not a valid descriptor.
87*8269e767SBrooks Davis.It Bq Er EINVAL
88*8269e767SBrooks DavisThe
89*8269e767SBrooks Davis.Fa namelen
90*8269e767SBrooks Davisargument is not a valid length for the address family.
91*8269e767SBrooks Davis.It Bq Er ENOTSOCK
92*8269e767SBrooks DavisThe
93*8269e767SBrooks Davis.Fa s
94*8269e767SBrooks Davisargument
95*8269e767SBrooks Davisis a descriptor for a file, not a socket.
96*8269e767SBrooks Davis.It Bq Er EADDRNOTAVAIL
97*8269e767SBrooks DavisThe specified address is not available on this machine.
98*8269e767SBrooks Davis.It Bq Er EAFNOSUPPORT
99*8269e767SBrooks DavisAddresses in the specified address family cannot be used with this socket.
100*8269e767SBrooks Davis.It Bq Er EISCONN
101*8269e767SBrooks DavisThe socket is already connected.
102*8269e767SBrooks Davis.It Bq Er ETIMEDOUT
103*8269e767SBrooks DavisConnection establishment timed out without establishing a connection.
104*8269e767SBrooks Davis.It Bq Er ECONNREFUSED
105*8269e767SBrooks DavisThe attempt to connect was forcefully rejected.
106*8269e767SBrooks Davis.It Bq Er ECONNRESET
107*8269e767SBrooks DavisThe connection was reset by the remote host.
108*8269e767SBrooks Davis.It Bq Er ENETUNREACH
109*8269e767SBrooks DavisThe network is not reachable from this host.
110*8269e767SBrooks Davis.It Bq Er EHOSTUNREACH
111*8269e767SBrooks DavisThe remote host is not reachable from this host.
112*8269e767SBrooks Davis.It Bq Er EADDRINUSE
113*8269e767SBrooks DavisThe address is already in use.
114*8269e767SBrooks Davis.It Bq Er EFAULT
115*8269e767SBrooks DavisThe
116*8269e767SBrooks Davis.Fa name
117*8269e767SBrooks Davisargument specifies an area outside
118*8269e767SBrooks Davisthe process address space.
119*8269e767SBrooks Davis.It Bq Er EINPROGRESS
120*8269e767SBrooks DavisThe socket is non-blocking
121*8269e767SBrooks Davisand the connection cannot
122*8269e767SBrooks Davisbe completed immediately.
123*8269e767SBrooks DavisIt is possible to
124*8269e767SBrooks Davis.Xr select 2
125*8269e767SBrooks Davisfor completion by selecting the socket for writing.
126*8269e767SBrooks Davis.It Bq Er EINTR
127*8269e767SBrooks DavisThe connection attempt was interrupted by the delivery of a signal.
128*8269e767SBrooks DavisThe connection will be established in the background,
129*8269e767SBrooks Davisas in the case of
130*8269e767SBrooks Davis.Er EINPROGRESS .
131*8269e767SBrooks Davis.It Bq Er EALREADY
132*8269e767SBrooks DavisA previous connection attempt has not yet been completed.
133*8269e767SBrooks Davis.It Bq Er EACCES
134*8269e767SBrooks DavisAn attempt is made to connect to a broadcast address (obtained through the
135*8269e767SBrooks Davis.Dv INADDR_BROADCAST
136*8269e767SBrooks Davisconstant or the
137*8269e767SBrooks Davis.Dv INADDR_NONE
138*8269e767SBrooks Davisreturn value) through a socket that does not provide broadcast functionality.
139*8269e767SBrooks Davis.It Bq Er EAGAIN
140*8269e767SBrooks DavisAn auto-assigned port number was requested but no auto-assigned ports
141*8269e767SBrooks Davisare available.
142*8269e767SBrooks DavisIncreasing the port range specified by
143*8269e767SBrooks Davis.Xr sysctl 3
144*8269e767SBrooks DavisMIB variables
145*8269e767SBrooks Davis.Va net.inet.ip.portrange.first
146*8269e767SBrooks Davisand
147*8269e767SBrooks Davis.Va net.inet.ip.portrange.last
148*8269e767SBrooks Davismay alleviate the problem.
149*8269e767SBrooks Davis.El
150*8269e767SBrooks Davis.Pp
151*8269e767SBrooks DavisThe following errors are specific to connecting names in the UNIX domain.
152*8269e767SBrooks DavisThese errors may not apply in future versions of the UNIX IPC domain.
153*8269e767SBrooks Davis.Bl -tag -width Er
154*8269e767SBrooks Davis.It Bq Er ENOTDIR
155*8269e767SBrooks DavisA component of the path prefix is not a directory.
156*8269e767SBrooks Davis.It Bq Er ENAMETOOLONG
157*8269e767SBrooks DavisA component of a pathname exceeded 255 characters,
158*8269e767SBrooks Davisor an entire path name exceeded 1023 characters.
159*8269e767SBrooks Davis.It Bq Er ENOENT
160*8269e767SBrooks DavisThe named socket does not exist.
161*8269e767SBrooks Davis.It Bq Er EACCES
162*8269e767SBrooks DavisSearch permission is denied for a component of the path prefix.
163*8269e767SBrooks Davis.It Bq Er EACCES
164*8269e767SBrooks DavisWrite access to the named socket is denied.
165*8269e767SBrooks Davis.It Bq Er ELOOP
166*8269e767SBrooks DavisToo many symbolic links were encountered in translating the pathname.
167*8269e767SBrooks Davis.It Bq Er EPERM
168*8269e767SBrooks DavisWrite access to the named socket is denied.
169*8269e767SBrooks Davis.El
170*8269e767SBrooks Davis.Sh SEE ALSO
171*8269e767SBrooks Davis.Xr accept 2 ,
172*8269e767SBrooks Davis.Xr getpeername 2 ,
173*8269e767SBrooks Davis.Xr getsockname 2 ,
174*8269e767SBrooks Davis.Xr select 2 ,
175*8269e767SBrooks Davis.Xr socket 2 ,
176*8269e767SBrooks Davis.Xr sysctl 3 ,
177*8269e767SBrooks Davis.Xr sysctl 8
178*8269e767SBrooks Davis.Sh HISTORY
179*8269e767SBrooks DavisThe
180*8269e767SBrooks Davis.Fn connect
181*8269e767SBrooks Davissystem call appeared in
182*8269e767SBrooks Davis.Bx 4.2 .
183