[unix-history] / usr / src / lib / libc / sys / connect.2

.\" Copyright (c) 1983 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)connect.2	6.6 (Berkeley) %G%
.\"
.TH CONNECT 2 ""
.UC 5
.SH NAME
connect \- initiate a connection on a socket
.SH SYNOPSIS
.nf
.ft B
#include <sys/types.h>
#include <sys/socket.h>
.PP
.ft B
connect(s, name, namelen)
int s;
struct sockaddr *name;
int namelen;
.fi
.SH DESCRIPTION
The parameter
.I s
is a socket.
If it is of type SOCK_DGRAM,
then 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 SOCK_STREAM,
then this call attempts to make a connection to
another socket.
The other socket is specified by
.I name,
which is an address in the communications space of the socket.
Each communications space interprets the
.I name
parameter in its own way.
Generally, stream sockets may successfully
.I connect
only once; datagram sockets may use
.I connect
multiple times to change their association.
Datagram sockets may dissolve the association
by connecting to an invalid address, such as a null address.
.SH "RETURN VALUE
If the connection or binding succeeds, then 0 is returned.
Otherwise a \-1 is returned, and a more specific error
code is stored in \fIerrno\fP.
.SH "ERRORS
The call fails if:
.TP 20
[EBADF]
.I S
is not a valid descriptor.
.TP 20
[ENOTSOCK]
.I S
is a descriptor for a file, not a socket.
.TP 20
[EADDRNOTAVAIL]
The specified address is not available on this machine.
.TP 20
[EAFNOSUPPORT]
Addresses in the specified address family cannot be used with this socket.
.TP 20
[EISCONN]
The socket is already connected.
.TP 20
[ETIMEDOUT]
Connection establishment timed out without establishing a connection.
.TP 20
[ECONNREFUSED]
The attempt to connect was forcefully rejected.
.TP 20
[ENETUNREACH]
The network isn't reachable from this host.
.TP 20
[EADDRINUSE]
The address is already in use.
.TP 20
[EFAULT]
The \fIname\fP parameter specifies an area outside
the process address space.
.TP 20
[EINPROGRESS]
The socket is non-blocking 
and the connection cannot
be completed immediately.
It is possible to
.IR select (2)
for completion by selecting the socket for writing.
.TP 20
[EALREADY]
The socket is non-blocking
and a previous connection attempt
has not yet been completed.
.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.
.TP 15
[ENOTDIR]
A component of the path prefix is not a directory.
.TP 15
[EINVAL]
The pathname contains a character with the high-order bit set.
.TP 15
[ENAMETOOLONG]
A component of a pathname exceeded 255 characters,
or an entire path name exceeded 1023 characters.
.TP 15
[ENOENT]
The named socket does not exist.
.TP 15
[EACCES]
Search permission is denied for a component of the path prefix.
.TP 15
[EACCES]
Write access to the named socket is denied.
.TP 15
[ELOOP]
Too many symbolic links were encountered in translating the pathname.
.SH SEE ALSO
accept(2), select(2), socket(2), getsockname(2)
Commit	Line	Data
5b41da86 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	.\"
d4bad45b	5	.\" @(#)connect.2 6.6 (Berkeley) %G%
5b41da86	6	.\"
bf25b211	7	.TH CONNECT 2 ""
5b41da86 KM	8	.UC 5
	9	.SH NAME
	10	connect \- initiate a connection on a socket
	11	.SH SYNOPSIS
	12	.nf
	13	.ft B
	14	#include <sys/types.h>
	15	#include <sys/socket.h>
	16	.PP
	17	.ft B
	18	connect(s, name, namelen)
	19	int s;
	20	struct sockaddr *name;
	21	int namelen;
	22	.fi
	23	.SH DESCRIPTION
	24	The parameter
	25	.I s
	26	is a socket.
	27	If it is of type SOCK_DGRAM,
56b0726a MK	28	then this call specifies the peer with which the socket is to be associated;
	29	this address is that to which datagrams are to be sent,
	30	and the only address from which datagrams are to be received.
	31	If the socket is of type SOCK_STREAM,
5b41da86 KM	32	then this call attempts to make a connection to
	33	another socket.
	34	The other socket is specified by
19914c9b	35	.I name,
5b41da86 KM	36	which is an address in the communications space of the socket.
	37	Each communications space interprets the
	38	.I name
	39	parameter in its own way.
56b0726a MK	40	Generally, stream sockets may successfully
	41	.I connect
	42	only once; datagram sockets may use
	43	.I connect
	44	multiple times to change their association.
	45	Datagram sockets may dissolve the association
	46	by connecting to an invalid address, such as a null address.
5b41da86 KM	47	.SH "RETURN VALUE
	48	If the connection or binding succeeds, then 0 is returned.
	49	Otherwise a \-1 is returned, and a more specific error
	50	code is stored in \fIerrno\fP.
	51	.SH "ERRORS
	52	The call fails if:
	53	.TP 20
	54	[EBADF]
	55	.I S
	56	is not a valid descriptor.
	57	.TP 20
	58	[ENOTSOCK]
	59	.I S
	60	is a descriptor for a file, not a socket.
	61	.TP 20
	62	[EADDRNOTAVAIL]
	63	The specified address is not available on this machine.
	64	.TP 20
	65	[EAFNOSUPPORT]
	66	Addresses in the specified address family cannot be used with this socket.
	67	.TP 20
	68	[EISCONN]
	69	The socket is already connected.
	70	.TP 20
	71	[ETIMEDOUT]
	72	Connection establishment timed out without establishing a connection.
	73	.TP 20
	74	[ECONNREFUSED]
	75	The attempt to connect was forcefully rejected.
	76	.TP 20
	77	[ENETUNREACH]
	78	The network isn't reachable from this host.
	79	.TP 20
	80	[EADDRINUSE]
	81	The address is already in use.
	82	.TP 20
	83	[EFAULT]
	84	The \fIname\fP parameter specifies an area outside
	85	the process address space.
	86	.TP 20
0d3f4d7d	87	[EINPROGRESS]
d4bad45b	88	The socket is non-blocking
5b41da86 KM	89	and the connection cannot
	90	be completed immediately.
	91	It is possible to
	92	.IR select (2)
0d3f4d7d	93	for completion by selecting the socket for writing.
56b0726a	94	.TP 20
0d3f4d7d	95	[EALREADY]
56b0726a MK	96	The socket is non-blocking
56b0726a MK	97	and a previous connection attempt
d4bad45b	98	has not yet been completed.
b5984ffe KM	99	.PP
b5984ffe KM	100	The following errors are specific to connecting names in the UNIX domain.
56b0726a	101	These errors may not apply in future versions of the UNIX IPC domain.
b5984ffe KM	102	.TP 15
	103	[ENOTDIR]
	104	A component of the path prefix is not a directory.
	105	.TP 15
	106	[EINVAL]
	107	The pathname contains a character with the high-order bit set.
	108	.TP 15
	109	[ENAMETOOLONG]
	110	A component of a pathname exceeded 255 characters,
	111	or an entire path name exceeded 1023 characters.
	112	.TP 15
	113	[ENOENT]
	114	The named socket does not exist.
	115	.TP 15
	116	[EACCES]
	117	Search permission is denied for a component of the path prefix.
	118	.TP 15
56b0726a MK	119	[EACCES]
	120	Write access to the named socket is denied.
	121	.TP 15
b5984ffe KM	122	[ELOOP]
b5984ffe KM	123	Too many symbolic links were encountered in translating the pathname.
5b41da86 KM	124	.SH SEE ALSO
5b41da86 KM	125	accept(2), select(2), socket(2), getsockname(2)