[apple/xnu.git] / bsd / man / man2 / connect.2

.\"	$NetBSD: connect.2,v 1.8 1995/10/12 15:40:48 jtc Exp $
.\"
.\" Copyright (c) 1983, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)connect.2	8.1 (Berkeley) 6/4/93
.\"
.Dd March 18, 2015
.Dt CONNECT 2
.Os BSD 4.2
.Sh NAME
.Nm connect
.Nd initiate a connection on a socket
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Ft int
.Fo connect
.Fa "int socket"
.Fa "const struct sockaddr *address"
.Fa "socklen_t address_len"
.Fc
.Sh DESCRIPTION
The parameter
.Fa socket
is a socket.
If it is of type
.Dv SOCK_DGRAM ,
this call specifies the peer with which the socket is to be associated;
this address is that to which datagrams are to be sent,
and the only address from which datagrams are to be received.
If the socket is of type
.Dv SOCK_STREAM ,
this call attempts to make a connection to
another socket.
The other socket is specified by
.Fa address ,
which is an address in the communications space of the socket.
.Pp
Each communications space interprets the
.Fa address
parameter in its own way.
Generally, stream sockets may successfully
.Fn connect
only once; datagram sockets may use
.Fn connect
multiple times to change their association.
Datagram sockets may dissolve the association
by calling
.Xr disconnectx 2 ,
or by connecting to an invalid address, such as a null address
or an address with 
the address family set to 
.Dv AF_UNSPEC 
(the error 
.Dv EAFNOSUPPORT 
will be harmlessly returned).
.Sh RETURN VALUES
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and the global integer variable
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn connect
system call will fail if:
.Bl -tag -width Er
.\" ==========
.It Bq Er EACCES
The destination address is a broadcast address and the 
socket option 
.Dv SO_BROADCAST 
is not set.
.\" ==========
.It Bq Er EADDRINUSE
The address is already in use.
.\" ==========
.It Bq Er EADDRNOTAVAIL
The specified address is not available on this machine.
.\" ==========
.It Bq Er EAFNOSUPPORT
Addresses in the specified address family cannot be used with this socket.
.\" ==========
.It Bq Er EALREADY
The socket is non-blocking
and a previous connection attempt
has not yet been completed.
.\" ==========
.It Bq Er EBADF
.Fa socket
is not a valid descriptor.
.\" ==========
.It Bq Er ECONNREFUSED
The attempt to connect was ignored
(because the target is not listening for connections)
or explicitly rejected.
.\" ==========
.It Bq Er EFAULT
The
.Fa address
parameter specifies an area outside
the process address space.
.\" ==========
.It Bq Er EHOSTUNREACH
The target host cannot be reached (e.g., down, disconnected).
.\" ==========
.It Bq Er EINPROGRESS
The socket is non-blocking 
and the connection cannot
be completed immediately.
It is possible to
.Xr select 2
for completion by selecting the socket for writing.
.\" ==========
.It Bq Er EINTR
Its execution was interrupted by a signal.
.\" ==========
.It Bq Er EINVAL
An invalid argument was detected
(e.g.,
.Fa address_len
is not valid for the address family,
the specified address family is invalid).
.\" ==========
.It Bq Er EISCONN
The socket is already connected.
.\" ==========
.It Bq Er ENETDOWN
The local network interface is not functioning.
.\" ==========
.It Bq Er ENETUNREACH
The network isn't reachable from this host.
.\" ==========
.It Bq Er ENOBUFS
The system call was unable to allocate a needed memory buffer.
.\" ==========
.It Bq Er ENOTSOCK
.Fa socket
is not a file descriptor for a socket.
.\" ==========
.It Bq Er EOPNOTSUPP
Because
.Fa socket
is listening, no connection is allowed.
.\" ==========
.It Bq Er EPROTOTYPE
.Fa address
has a different type than the socket
that is bound to the specified peer address.
.\" ==========
.It Bq Er ETIMEDOUT
Connection establishment timed out without establishing a connection.
.\" ==========
.It Bq Er ECONNRESET
Remote host reset the connection request.
.El
.Pp
The following errors are specific to connecting names in the UNIX domain.
These errors may not apply in future versions of the UNIX IPC domain.
.Bl -tag -width Er
.\" ==========
.It Bq Er EACCES
Search permission is denied for a component of the path prefix.
.\" ==========
.It Bq Er EACCES
Write access to the named socket is denied.
.\" ==========
.It Bq Er EIO
An I/O error occurred while reading from or writing to the file system.
.\" ==========
.It Bq Er ELOOP
Too many symbolic links were encountered in translating the pathname.
This is taken to be indicative of a looping symbolic link.
.\" ==========
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded 
.Dv {NAME_MAX}
characters, or an entire path name exceeded 
.Dv {PATH_MAX}
characters.
.\" ==========
.It Bq Er ENOENT
The named socket does not exist.
.\" ==========
.It Bq Er ENOTDIR
A component of the path prefix is not a directory.
.El
.Sh LEGACY SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Pp
The include file
.In sys/types.h
is necessary.
.Sh SEE ALSO
.Xr accept 2 ,
.Xr connectx 2 ,
.Xr disconnectx 2 ,
.Xr getsockname 2 ,
.Xr select 2 ,
.Xr socket 2 ,
.Xr compat 5
.Sh HISTORY
The
.Fn connect
function call appeared in
.Bx 4.2 .
Commit	Line	Data
9bccf70c A	1	.\" $NetBSD: connect.2,v 1.8 1995/10/12 15:40:48 jtc Exp $
	2	.\"
	3	.\" Copyright (c) 1983, 1993
	4	.\" The Regents of the University of California. All rights reserved.
	5	.\"
	6	.\" Redistribution and use in source and binary forms, with or without
	7	.\" modification, are permitted provided that the following conditions
	8	.\" are met:
	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.
	21	.\"
	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
	32	.\" SUCH DAMAGE.
	33	.\"
	34	.\" @(#)connect.2 8.1 (Berkeley) 6/4/93
	35	.\"
3e170ce0	36	.Dd March 18, 2015
9bccf70c A	37	.Dt CONNECT 2
	38	.Os BSD 4.2
	39	.Sh NAME
	40	.Nm connect
	41	.Nd initiate a connection on a socket
	42	.Sh SYNOPSIS
	43	.Fd #include <sys/types.h>
	44	.Fd #include <sys/socket.h>
	45	.Ft int
2d21ac55 A	46	.Fo connect
	47	.Fa "int socket"
	48	.Fa "const struct sockaddr *address"
	49	.Fa "socklen_t address_len"
	50	.Fc
9bccf70c A	51	.Sh DESCRIPTION
9bccf70c A	52	The parameter
2d21ac55	53	.Fa socket
9bccf70c A	54	is a socket.
	55	If it is of type
	56	.Dv SOCK_DGRAM ,
	57	this call specifies the peer with which the socket is to be associated;
	58	this address is that to which datagrams are to be sent,
	59	and the only address from which datagrams are to be received.
	60	If the socket is of type
	61	.Dv SOCK_STREAM ,
	62	this call attempts to make a connection to
	63	another socket.
	64	The other socket is specified by
2d21ac55	65	.Fa address ,
9bccf70c	66	which is an address in the communications space of the socket.
2d21ac55	67	.Pp
9bccf70c	68	Each communications space interprets the
2d21ac55	69	.Fa address
9bccf70c A	70	parameter in its own way.
	71	Generally, stream sockets may successfully
	72	.Fn connect
	73	only once; datagram sockets may use
	74	.Fn connect
	75	multiple times to change their association.
	76	Datagram sockets may dissolve the association
3e170ce0 A	77	by calling
	78	.Xr disconnectx 2 ,
	79	or by connecting to an invalid address, such as a null address
55e303ae	80	or an address with
91447636 A	81	the address family set to
	82	.Dv AF_UNSPEC
	83	(the error
	84	.Dv EAFNOSUPPORT
	85	will be harmlessly returned).
9bccf70c	86	.Sh RETURN VALUES
2d21ac55 A	87	Upon successful completion, a value of 0 is returned.
	88	Otherwise, a value of -1 is returned and the global integer variable
	89	.Va errno
	90	is set to indicate the error.
9bccf70c A	91	.Sh ERRORS
	92	The
	93	.Fn connect
2d21ac55	94	system call will fail if:
9bccf70c	95	.Bl -tag -width Er
2d21ac55 A	96	.\" ==========
	97	.It Bq Er EACCES
	98	The destination address is a broadcast address and the
	99	socket option
	100	.Dv SO_BROADCAST
	101	is not set.
	102	.\" ==========
	103	.It Bq Er EADDRINUSE
	104	The address is already in use.
	105	.\" ==========
9bccf70c A	106	.It Bq Er EADDRNOTAVAIL
9bccf70c A	107	The specified address is not available on this machine.
2d21ac55	108	.\" ==========
9bccf70c A	109	.It Bq Er EAFNOSUPPORT
9bccf70c A	110	Addresses in the specified address family cannot be used with this socket.
2d21ac55 A	111	.\" ==========
	112	.It Bq Er EALREADY
	113	The socket is non-blocking
	114	and a previous connection attempt
	115	has not yet been completed.
	116	.\" ==========
	117	.It Bq Er EBADF
	118	.Fa socket
	119	is not a valid descriptor.
	120	.\" ==========
9bccf70c	121	.It Bq Er ECONNREFUSED
2d21ac55 A	122	The attempt to connect was ignored
	123	(because the target is not listening for connections)
	124	or explicitly rejected.
	125	.\" ==========
9bccf70c A	126	.It Bq Er EFAULT
9bccf70c A	127	The
2d21ac55	128	.Fa address
9bccf70c A	129	parameter specifies an area outside
9bccf70c A	130	the process address space.
2d21ac55 A	131	.\" ==========
	132	.It Bq Er EHOSTUNREACH
	133	The target host cannot be reached (e.g., down, disconnected).
	134	.\" ==========
9bccf70c A	135	.It Bq Er EINPROGRESS
	136	The socket is non-blocking
	137	and the connection cannot
	138	be completed immediately.
	139	It is possible to
	140	.Xr select 2
	141	for completion by selecting the socket for writing.
2d21ac55 A	142	.\" ==========
	143	.It Bq Er EINTR
	144	Its execution was interrupted by a signal.
	145	.\" ==========
	146	.It Bq Er EINVAL
	147	An invalid argument was detected
	148	(e.g.,
	149	.Fa address_len
	150	is not valid for the address family,
	151	the specified address family is invalid).
	152	.\" ==========
	153	.It Bq Er EISCONN
	154	The socket is already connected.
	155	.\" ==========
	156	.It Bq Er ENETDOWN
	157	The local network interface is not functioning.
	158	.\" ==========
	159	.It Bq Er ENETUNREACH
	160	The network isn't reachable from this host.
	161	.\" ==========
	162	.It Bq Er ENOBUFS
	163	The system call was unable to allocate a needed memory buffer.
	164	.\" ==========
	165	.It Bq Er ENOTSOCK
	166	.Fa socket
	167	is not a file descriptor for a socket.
	168	.\" ==========
	169	.It Bq Er EOPNOTSUPP
	170	Because
	171	.Fa socket
	172	is listening, no connection is allowed.
	173	.\" ==========
	174	.It Bq Er EPROTOTYPE
	175	.Fa address
	176	has a different type than the socket
	177	that is bound to the specified peer address.
	178	.\" ==========
	179	.It Bq Er ETIMEDOUT
	180	Connection establishment timed out without establishing a connection.
b0d623f7 A	181	.\" ==========
	182	.It Bq Er ECONNRESET
	183	Remote host reset the connection request.
9bccf70c A	184	.El
	185	.Pp
	186	The following errors are specific to connecting names in the UNIX domain.
	187	These errors may not apply in future versions of the UNIX IPC domain.
	188	.Bl -tag -width Er
2d21ac55 A	189	.\" ==========
	190	.It Bq Er EACCES
	191	Search permission is denied for a component of the path prefix.
	192	.\" ==========
	193	.It Bq Er EACCES
	194	Write access to the named socket is denied.
	195	.\" ==========
	196	.It Bq Er EIO
	197	An I/O error occurred while reading from or writing to the file system.
	198	.\" ==========
	199	.It Bq Er ELOOP
	200	Too many symbolic links were encountered in translating the pathname.
	201	This is taken to be indicative of a looping symbolic link.
	202	.\" ==========
9bccf70c A	203	.It Bq Er ENAMETOOLONG
	204	A component of a pathname exceeded
	205	.Dv {NAME_MAX}
	206	characters, or an entire path name exceeded
	207	.Dv {PATH_MAX}
	208	characters.
2d21ac55	209	.\" ==========
9bccf70c A	210	.It Bq Er ENOENT
9bccf70c A	211	The named socket does not exist.
2d21ac55 A	212	.\" ==========
	213	.It Bq Er ENOTDIR
	214	A component of the path prefix is not a directory.
9bccf70c	215	.El
2d21ac55 A	216	.Sh LEGACY SYNOPSIS
	217	.Fd #include <sys/types.h>
	218	.Fd #include <sys/socket.h>
	219	.Pp
	220	The include file
	221	.In sys/types.h
	222	is necessary.
9bccf70c A	223	.Sh SEE ALSO
9bccf70c A	224	.Xr accept 2 ,
3e170ce0 A	225	.Xr connectx 2 ,
3e170ce0 A	226	.Xr disconnectx 2 ,
2d21ac55	227	.Xr getsockname 2 ,
9bccf70c A	228	.Xr select 2 ,
9bccf70c A	229	.Xr socket 2 ,
2d21ac55	230	.Xr compat 5
9bccf70c A	231	.Sh HISTORY
	232	The
	233	.Fn connect
	234	function call appeared in
	235	.Bx 4.2 .