2004-11-03 13:51:07 +00:00
|
|
|
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
|
|
.\"
|
|
|
|
.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
|
|
|
|
.\" Portions extracted from /usr/include/sys/socket.h, which does not have
|
|
|
|
.\" any authorship information in it. It is probably available under the GPL.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\"
|
|
|
|
.\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page:
|
|
|
|
.\"
|
|
|
|
.\" Copyright (c) 1983 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.
|
|
|
|
.\"
|
|
|
|
.\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
|
|
|
|
.\" Modified 1998, 1999 by Andi Kleen
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified 2004-06-23 by Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.TH CONNECT 2 2004-06-23 "Linux 2.6.7" "Linux Programmer's Manual"
|
|
|
|
.SH NAME
|
|
|
|
connect \- initiate a connection on a socket
|
|
|
|
.SH SYNOPSIS
|
2007-04-03 14:04:54 +00:00
|
|
|
.nf
|
2004-11-03 13:51:07 +00:00
|
|
|
.B #include <sys/types.h>
|
|
|
|
.br
|
|
|
|
.B #include <sys/socket.h>
|
|
|
|
.sp
|
|
|
|
.BI "int connect(int " sockfd ", const struct sockaddr *" serv_addr ,
|
2007-04-03 14:04:54 +00:00
|
|
|
.BI " socklen_t " addrlen );
|
|
|
|
.fi
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
2005-06-30 10:29:56 +00:00
|
|
|
The
|
|
|
|
.BR connect ()
|
|
|
|
system call connects the socket referred to by the file descriptor
|
2004-11-03 13:51:07 +00:00
|
|
|
.I sockfd
|
2005-06-30 10:29:56 +00:00
|
|
|
to the address specified by
|
|
|
|
.IR serv_addr .
|
|
|
|
The
|
2007-04-12 22:42:49 +00:00
|
|
|
.IR addrlen
|
2005-06-30 10:29:56 +00:00
|
|
|
argument specifies the size of
|
|
|
|
.IR serv_addr .
|
|
|
|
The format of the address in
|
|
|
|
.I serv_addr
|
|
|
|
is determined by the address space of the socket
|
|
|
|
.IR sockfd ;
|
|
|
|
see
|
|
|
|
.BR socket (2)
|
|
|
|
for further details.
|
|
|
|
|
|
|
|
If the socket
|
|
|
|
.I sockfd
|
|
|
|
is of type
|
2004-11-03 13:51:07 +00:00
|
|
|
.B SOCK_DGRAM
|
2005-06-30 10:29:56 +00:00
|
|
|
then
|
2004-11-03 13:51:07 +00:00
|
|
|
.I serv_addr
|
2005-06-30 10:29:56 +00:00
|
|
|
is the address to which datagrams are sent by default, and the only
|
2007-04-12 22:42:49 +00:00
|
|
|
address from which datagrams are received.
|
|
|
|
If the socket is of type
|
2004-11-03 13:51:07 +00:00
|
|
|
.B SOCK_STREAM
|
|
|
|
or
|
|
|
|
.BR SOCK_SEQPACKET ,
|
2005-06-30 10:29:56 +00:00
|
|
|
this call attempts to make a connection to the socket that is bound
|
|
|
|
to the address specified by
|
|
|
|
.IR serv_addr .
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
Generally, connection-based protocol sockets may successfully
|
2005-06-30 10:29:56 +00:00
|
|
|
.BR connect ()
|
2004-11-03 13:51:07 +00:00
|
|
|
only once; connectionless protocol sockets may use
|
2005-06-30 10:29:56 +00:00
|
|
|
.BR connect ()
|
2007-04-12 22:42:49 +00:00
|
|
|
multiple times to change their association.
|
|
|
|
Connectionless sockets may
|
|
|
|
dissolve the association by connecting to an address with the
|
2004-11-03 13:51:07 +00:00
|
|
|
.I sa_family
|
|
|
|
member of
|
2007-04-12 22:42:49 +00:00
|
|
|
.B sockaddr
|
|
|
|
set to
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR AF_UNSPEC .
|
|
|
|
.SH "RETURN VALUE"
|
2007-04-12 22:42:49 +00:00
|
|
|
If the connection or binding succeeds, zero is returned.
|
|
|
|
On error, \-1 is returned, and
|
2004-11-03 13:51:07 +00:00
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
|
|
|
.SH ERRORS
|
2007-04-12 22:42:49 +00:00
|
|
|
The following are general socket errors only.
|
|
|
|
There may be other domain-specific error codes.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EACCES
|
|
|
|
For Unix domain sockets, which are identified by pathname:
|
|
|
|
Write permission is denied on the socket file,
|
|
|
|
or search permission is denied for one of the directories
|
|
|
|
in the path prefix.
|
|
|
|
(See also
|
|
|
|
.BR path_resolution (2).)
|
|
|
|
.TP
|
|
|
|
.B EACCES, EPERM
|
2007-04-12 22:42:49 +00:00
|
|
|
The user tried to connect to a broadcast address without having the socket
|
2004-11-03 13:51:07 +00:00
|
|
|
broadcast flag enabled or the connection request failed because of a local
|
|
|
|
firewall rule.
|
|
|
|
.TP
|
|
|
|
.B EADDRINUSE
|
|
|
|
Local address is already in use.
|
|
|
|
.TP
|
|
|
|
.B EAFNOSUPPORT
|
2007-04-12 22:42:49 +00:00
|
|
|
The passed address didn't have the correct address family in its
|
2004-11-03 13:51:07 +00:00
|
|
|
.I sa_family
|
|
|
|
field.
|
|
|
|
.TP
|
|
|
|
.B EAGAIN
|
2007-04-12 22:42:49 +00:00
|
|
|
No more free local ports or insufficient entries in the routing cache.
|
|
|
|
For
|
2004-11-03 13:51:07 +00:00
|
|
|
.B PF_INET
|
2007-04-12 22:42:49 +00:00
|
|
|
see the
|
2004-11-03 13:51:07 +00:00
|
|
|
.B net.ipv4.ip_local_port_range
|
2007-04-12 22:42:49 +00:00
|
|
|
sysctl in
|
|
|
|
.BR ip (7)
|
2004-11-03 13:51:07 +00:00
|
|
|
on how to increase the number of local ports.
|
|
|
|
.TP
|
|
|
|
.B EALREADY
|
|
|
|
The socket is non-blocking and a previous connection attempt has not yet
|
|
|
|
been completed.
|
|
|
|
.TP
|
|
|
|
.B EBADF
|
|
|
|
The file descriptor is not a valid index in the descriptor table.
|
|
|
|
.TP
|
|
|
|
.B ECONNREFUSED
|
|
|
|
No one listening on the remote address.
|
|
|
|
.TP
|
|
|
|
.B EFAULT
|
|
|
|
The socket structure address is outside the user's address space.
|
|
|
|
.TP
|
|
|
|
.B EINPROGRESS
|
|
|
|
The socket is non-blocking and the connection cannot be completed
|
2007-04-12 22:42:49 +00:00
|
|
|
immediately.
|
|
|
|
It is possible to
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR select (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
or
|
|
|
|
.BR poll (2)
|
|
|
|
for completion by selecting the socket for writing.
|
|
|
|
After
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR select (2)
|
2004-11-03 13:51:07 +00:00
|
|
|
indicates writability, use
|
|
|
|
.BR getsockopt (2)
|
2007-04-12 22:42:49 +00:00
|
|
|
to read the
|
2004-11-03 13:51:07 +00:00
|
|
|
.B SO_ERROR
|
2007-04-12 22:42:49 +00:00
|
|
|
option at level
|
2004-11-03 13:51:07 +00:00
|
|
|
.B SOL_SOCKET
|
2007-04-12 22:42:49 +00:00
|
|
|
to determine whether
|
2005-06-30 10:29:56 +00:00
|
|
|
.BR connect ()
|
2007-04-12 22:42:49 +00:00
|
|
|
completed successfully
|
2004-11-03 13:51:07 +00:00
|
|
|
.RB ( SO_ERROR
|
2007-04-12 22:42:49 +00:00
|
|
|
is zero) or unsuccessfully
|
2004-11-03 13:51:07 +00:00
|
|
|
.RB ( SO_ERROR
|
2007-04-12 22:42:49 +00:00
|
|
|
is one of the usual error codes listed here,
|
2004-11-03 13:51:07 +00:00
|
|
|
explaining the reason for the failure).
|
|
|
|
.TP
|
2005-07-25 11:22:58 +00:00
|
|
|
.B EINTR
|
|
|
|
The system call was interrupted by a signal that was caught.
|
|
|
|
.\" For TCP, the connection will complete asynchronously.
|
|
|
|
.\" See http://lkml.org/lkml/2005/7/12/254
|
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B EISCONN
|
|
|
|
The socket is already connected.
|
|
|
|
.TP
|
|
|
|
.B ENETUNREACH
|
|
|
|
Network is unreachable.
|
|
|
|
.TP
|
|
|
|
.B ENOTSOCK
|
|
|
|
The file descriptor is not associated with a socket.
|
|
|
|
.TP
|
|
|
|
.B ETIMEDOUT
|
2007-04-12 22:42:49 +00:00
|
|
|
Timeout while attempting connection.
|
|
|
|
The server may be too
|
|
|
|
busy to accept new connections.
|
|
|
|
Note that for IP sockets the timeout may
|
2004-11-03 13:51:07 +00:00
|
|
|
be very long when syncookies are enabled on the server.
|
|
|
|
.SH "CONFORMING TO"
|
2006-12-17 01:34:44 +00:00
|
|
|
SVr4, 4.4BSD, (the
|
2005-06-30 10:29:56 +00:00
|
|
|
.BR connect ()
|
2007-04-12 22:42:49 +00:00
|
|
|
function first appeared in 4.2BSD), POSIX.1-2001.
|
2006-08-04 09:41:28 +00:00
|
|
|
.\" SVr4 documents the additional
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" general error codes
|
|
|
|
.\" .BR EADDRNOTAVAIL ,
|
|
|
|
.\" .BR EINVAL ,
|
|
|
|
.\" .BR EAFNOSUPPORT ,
|
|
|
|
.\" .BR EALREADY ,
|
|
|
|
.\" .BR EINTR ,
|
|
|
|
.\" .BR EPROTOTYPE ,
|
2006-08-04 09:41:28 +00:00
|
|
|
.\" and
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" .BR ENOSR .
|
2006-08-04 09:41:28 +00:00
|
|
|
.\" It also
|
|
|
|
.\" documents many additional error conditions not described here.
|
2007-05-16 02:54:18 +00:00
|
|
|
.SH NOTES
|
2004-11-03 13:51:07 +00:00
|
|
|
The third argument of
|
2005-06-30 10:29:56 +00:00
|
|
|
.BR connect ()
|
|
|
|
is in reality an
|
|
|
|
.I int
|
2005-07-18 15:05:56 +00:00
|
|
|
(and this is what 4.x BSD and libc4 and libc5 have).
|
2007-04-12 22:42:49 +00:00
|
|
|
Some POSIX confusion resulted in the present
|
2005-06-30 10:29:56 +00:00
|
|
|
.IR socklen_t ,
|
|
|
|
also used by glibc.
|
2004-11-03 13:51:07 +00:00
|
|
|
See also
|
|
|
|
.BR accept (2).
|
|
|
|
.SH BUGS
|
|
|
|
Unconnecting a socket by calling
|
2005-06-30 10:29:56 +00:00
|
|
|
.BR connect ()
|
2004-11-03 13:51:07 +00:00
|
|
|
with a
|
|
|
|
.B AF_UNSPEC
|
|
|
|
address is not yet implemented.
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR accept (2),
|
|
|
|
.BR bind (2),
|
|
|
|
.BR getsockname (2),
|
|
|
|
.BR listen (2),
|
|
|
|
.BR path_resolution (2),
|
|
|
|
.BR socket (2)
|