[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 June 4, 1993
.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 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.
.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 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	.\"
	36	.Dd June 4, 1993
	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
55e303ae A	77	by connecting to an invalid address, such as a null address
55e303ae A	78	or an address with
91447636 A	79	the address family set to
	80	.Dv AF_UNSPEC
	81	(the error
	82	.Dv EAFNOSUPPORT
	83	will be harmlessly returned).
9bccf70c	84	.Sh RETURN VALUES
2d21ac55 A	85	Upon successful completion, a value of 0 is returned.
	86	Otherwise, a value of -1 is returned and the global integer variable
	87	.Va errno
	88	is set to indicate the error.
9bccf70c A	89	.Sh ERRORS
	90	The
	91	.Fn connect
2d21ac55	92	system call will fail if:
9bccf70c	93	.Bl -tag -width Er
2d21ac55 A	94	.\" ==========
	95	.It Bq Er EACCES
	96	The destination address is a broadcast address and the
	97	socket option
	98	.Dv SO_BROADCAST
	99	is not set.
	100	.\" ==========
	101	.It Bq Er EADDRINUSE
	102	The address is already in use.
	103	.\" ==========
9bccf70c A	104	.It Bq Er EADDRNOTAVAIL
9bccf70c A	105	The specified address is not available on this machine.
2d21ac55	106	.\" ==========
9bccf70c A	107	.It Bq Er EAFNOSUPPORT
9bccf70c A	108	Addresses in the specified address family cannot be used with this socket.
2d21ac55 A	109	.\" ==========
	110	.It Bq Er EALREADY
	111	The socket is non-blocking
	112	and a previous connection attempt
	113	has not yet been completed.
	114	.\" ==========
	115	.It Bq Er EBADF
	116	.Fa socket
	117	is not a valid descriptor.
	118	.\" ==========
9bccf70c	119	.It Bq Er ECONNREFUSED
2d21ac55 A	120	The attempt to connect was ignored
	121	(because the target is not listening for connections)
	122	or explicitly rejected.
	123	.\" ==========
9bccf70c A	124	.It Bq Er EFAULT
9bccf70c A	125	The
2d21ac55	126	.Fa address
9bccf70c A	127	parameter specifies an area outside
9bccf70c A	128	the process address space.
2d21ac55 A	129	.\" ==========
	130	.It Bq Er EHOSTUNREACH
	131	The target host cannot be reached (e.g., down, disconnected).
	132	.\" ==========
9bccf70c A	133	.It Bq Er EINPROGRESS
	134	The socket is non-blocking
	135	and the connection cannot
	136	be completed immediately.
	137	It is possible to
	138	.Xr select 2
	139	for completion by selecting the socket for writing.
2d21ac55 A	140	.\" ==========
	141	.It Bq Er EINTR
	142	Its execution was interrupted by a signal.
	143	.\" ==========
	144	.It Bq Er EINVAL
	145	An invalid argument was detected
	146	(e.g.,
	147	.Fa address_len
	148	is not valid for the address family,
	149	the specified address family is invalid).
	150	.\" ==========
	151	.It Bq Er EISCONN
	152	The socket is already connected.
	153	.\" ==========
	154	.It Bq Er ENETDOWN
	155	The local network interface is not functioning.
	156	.\" ==========
	157	.It Bq Er ENETUNREACH
	158	The network isn't reachable from this host.
	159	.\" ==========
	160	.It Bq Er ENOBUFS
	161	The system call was unable to allocate a needed memory buffer.
	162	.\" ==========
	163	.It Bq Er ENOTSOCK
	164	.Fa socket
	165	is not a file descriptor for a socket.
	166	.\" ==========
	167	.It Bq Er EOPNOTSUPP
	168	Because
	169	.Fa socket
	170	is listening, no connection is allowed.
	171	.\" ==========
	172	.It Bq Er EPROTOTYPE
	173	.Fa address
	174	has a different type than the socket
	175	that is bound to the specified peer address.
	176	.\" ==========
	177	.It Bq Er ETIMEDOUT
	178	Connection establishment timed out without establishing a connection.
9bccf70c A	179	.El
	180	.Pp
	181	The following errors are specific to connecting names in the UNIX domain.
	182	These errors may not apply in future versions of the UNIX IPC domain.
	183	.Bl -tag -width Er
2d21ac55 A	184	.\" ==========
	185	.It Bq Er EACCES
	186	Search permission is denied for a component of the path prefix.
	187	.\" ==========
	188	.It Bq Er EACCES
	189	Write access to the named socket is denied.
	190	.\" ==========
	191	.It Bq Er EIO
	192	An I/O error occurred while reading from or writing to the file system.
	193	.\" ==========
	194	.It Bq Er ELOOP
	195	Too many symbolic links were encountered in translating the pathname.
	196	This is taken to be indicative of a looping symbolic link.
	197	.\" ==========
9bccf70c A	198	.It Bq Er ENAMETOOLONG
	199	A component of a pathname exceeded
	200	.Dv {NAME_MAX}
	201	characters, or an entire path name exceeded
	202	.Dv {PATH_MAX}
	203	characters.
2d21ac55	204	.\" ==========
9bccf70c A	205	.It Bq Er ENOENT
9bccf70c A	206	The named socket does not exist.
2d21ac55 A	207	.\" ==========
	208	.It Bq Er ENOTDIR
	209	A component of the path prefix is not a directory.
9bccf70c	210	.El
2d21ac55 A	211	.Sh LEGACY SYNOPSIS
	212	.Fd #include <sys/types.h>
	213	.Fd #include <sys/socket.h>
	214	.Pp
	215	The include file
	216	.In sys/types.h
	217	is necessary.
9bccf70c A	218	.Sh SEE ALSO
9bccf70c A	219	.Xr accept 2 ,
2d21ac55	220	.Xr getsockname 2 ,
9bccf70c A	221	.Xr select 2 ,
9bccf70c A	222	.Xr socket 2 ,
2d21ac55	223	.Xr compat 5
9bccf70c A	224	.Sh HISTORY
	225	The
	226	.Fn connect
	227	function call appeared in
	228	.Bx 4.2 .