|
Packit |
7cfc04 |
.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu)
|
|
Packit |
7cfc04 |
.\" Portions extracted from /usr/include/sys/socket.h, which does not have
|
|
Packit |
7cfc04 |
.\" any authorship information in it. It is probably available under the GPL.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(VERBATIM)
|
|
Packit |
7cfc04 |
.\" Permission is granted to make and distribute verbatim copies of this
|
|
Packit |
7cfc04 |
.\" manual provided the copyright notice and this permission notice are
|
|
Packit |
7cfc04 |
.\" preserved on all copies.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Permission is granted to copy and distribute modified versions of this
|
|
Packit |
7cfc04 |
.\" manual under the conditions for verbatim copying, provided that the
|
|
Packit |
7cfc04 |
.\" entire resulting derived work is distributed under the terms of a
|
|
Packit |
7cfc04 |
.\" permission notice identical to this one.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
Packit |
7cfc04 |
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
Packit |
7cfc04 |
.\" responsibility for errors or omissions, or for damages resulting from
|
|
Packit |
7cfc04 |
.\" the use of the information contained herein. The author(s) may not
|
|
Packit |
7cfc04 |
.\" have taken the same level of care in the production of this manual,
|
|
Packit |
7cfc04 |
.\" which is licensed free of charge, as they might when working
|
|
Packit |
7cfc04 |
.\" professionally.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
Packit |
7cfc04 |
.\" the source, must acknowledge the copyright and authors of this work.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Other portions are from the 6.9 (Berkeley) 3/10/91 man page:
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Copyright (c) 1983 The Regents of the University of California.
|
|
Packit |
7cfc04 |
.\" All rights reserved.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
|
|
Packit |
7cfc04 |
.\" Redistribution and use in source and binary forms, with or without
|
|
Packit |
7cfc04 |
.\" modification, are permitted provided that the following conditions
|
|
Packit |
7cfc04 |
.\" are met:
|
|
Packit |
7cfc04 |
.\" 1. Redistributions of source code must retain the above copyright
|
|
Packit |
7cfc04 |
.\" notice, this list of conditions and the following disclaimer.
|
|
Packit |
7cfc04 |
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
Packit |
7cfc04 |
.\" notice, this list of conditions and the following disclaimer in the
|
|
Packit |
7cfc04 |
.\" documentation and/or other materials provided with the distribution.
|
|
Packit |
7cfc04 |
.\" 3. All advertising materials mentioning features or use of this software
|
|
Packit |
7cfc04 |
.\" must display the following acknowledgement:
|
|
Packit |
7cfc04 |
.\" This product includes software developed by the University of
|
|
Packit |
7cfc04 |
.\" California, Berkeley and its contributors.
|
|
Packit |
7cfc04 |
.\" 4. Neither the name of the University nor the names of its contributors
|
|
Packit |
7cfc04 |
.\" may be used to endorse or promote products derived from this software
|
|
Packit |
7cfc04 |
.\" without specific prior written permission.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
Packit |
7cfc04 |
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
Packit |
7cfc04 |
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
Packit |
7cfc04 |
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
Packit |
7cfc04 |
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
Packit |
7cfc04 |
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
Packit |
7cfc04 |
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
Packit |
7cfc04 |
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
Packit |
7cfc04 |
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
Packit |
7cfc04 |
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
Packit |
7cfc04 |
.\" SUCH DAMAGE.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
|
|
Packit |
7cfc04 |
.\" Modified 1998, 1999 by Andi Kleen
|
|
Packit |
7cfc04 |
.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH CONNECT 2 2017-09-15 "Linux" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
connect \- initiate a connection on a socket
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
.BR "#include <sys/types.h>" " /* See NOTES */"
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
.B #include <sys/socket.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "int connect(int " sockfd ", const struct sockaddr *" addr ,
|
|
Packit |
7cfc04 |
.BI " socklen_t " addrlen );
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR connect ()
|
|
Packit |
7cfc04 |
system call connects the socket referred to by the file descriptor
|
|
Packit |
7cfc04 |
.I sockfd
|
|
Packit |
7cfc04 |
to the address specified by
|
|
Packit |
7cfc04 |
.IR addr .
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I addrlen
|
|
Packit |
7cfc04 |
argument specifies the size of
|
|
Packit |
7cfc04 |
.IR addr .
|
|
Packit |
7cfc04 |
The format of the address in
|
|
Packit |
7cfc04 |
.I addr
|
|
Packit |
7cfc04 |
is determined by the address space of the socket
|
|
Packit |
7cfc04 |
.IR sockfd ;
|
|
Packit |
7cfc04 |
see
|
|
Packit |
7cfc04 |
.BR socket (2)
|
|
Packit |
7cfc04 |
for further details.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If the socket
|
|
Packit |
7cfc04 |
.I sockfd
|
|
Packit |
7cfc04 |
is of type
|
|
Packit |
7cfc04 |
.BR SOCK_DGRAM ,
|
|
Packit |
7cfc04 |
then
|
|
Packit |
7cfc04 |
.I addr
|
|
Packit |
7cfc04 |
is the address to which datagrams are sent by default, and the only
|
|
Packit |
7cfc04 |
address from which datagrams are received.
|
|
Packit |
7cfc04 |
If the socket is of type
|
|
Packit |
7cfc04 |
.B SOCK_STREAM
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR SOCK_SEQPACKET ,
|
|
Packit |
7cfc04 |
this call attempts to make a connection to the socket that is bound
|
|
Packit |
7cfc04 |
to the address specified by
|
|
Packit |
7cfc04 |
.IR addr .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Generally, connection-based protocol sockets may successfully
|
|
Packit |
7cfc04 |
.BR connect ()
|
|
Packit |
7cfc04 |
only once; connectionless protocol sockets may use
|
|
Packit |
7cfc04 |
.BR connect ()
|
|
Packit |
7cfc04 |
multiple times to change their association.
|
|
Packit |
7cfc04 |
Connectionless sockets may
|
|
Packit |
7cfc04 |
dissolve the association by connecting to an address with the
|
|
Packit |
7cfc04 |
.I sa_family
|
|
Packit |
7cfc04 |
member of
|
|
Packit |
7cfc04 |
.I sockaddr
|
|
Packit |
7cfc04 |
set to
|
|
Packit |
7cfc04 |
.BR AF_UNSPEC
|
|
Packit |
7cfc04 |
(supported on Linux since kernel 2.2).
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
If the connection or binding succeeds, zero is returned.
|
|
Packit |
7cfc04 |
On error, \-1 is returned, and
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
is set appropriately.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
The following are general socket errors only.
|
|
Packit |
7cfc04 |
There may be other domain-specific error codes.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EACCES
|
|
Packit |
7cfc04 |
For UNIX domain sockets, which are identified by pathname:
|
|
Packit |
7cfc04 |
Write permission is denied on the socket file,
|
|
Packit |
7cfc04 |
or search permission is denied for one of the directories
|
|
Packit |
7cfc04 |
in the path prefix.
|
|
Packit |
7cfc04 |
(See also
|
|
Packit |
7cfc04 |
.BR path_resolution (7).)
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EACCES ", " EPERM
|
|
Packit |
7cfc04 |
The user tried to connect to a broadcast address without having the socket
|
|
Packit |
7cfc04 |
broadcast flag enabled or the connection request failed because of a local
|
|
Packit |
7cfc04 |
firewall rule.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EADDRINUSE
|
|
Packit |
7cfc04 |
Local address is already in use.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EADDRNOTAVAIL
|
|
Packit |
7cfc04 |
(Internet domain sockets)
|
|
Packit |
7cfc04 |
The socket referred to by
|
|
Packit |
7cfc04 |
.I sockfd
|
|
Packit |
7cfc04 |
had not previously been bound to an address and,
|
|
Packit |
7cfc04 |
upon attempting to bind it to an ephemeral port,
|
|
Packit |
7cfc04 |
it was determined that all port numbers in the ephemeral port range
|
|
Packit |
7cfc04 |
are currently in use.
|
|
Packit |
7cfc04 |
See the discussion of
|
|
Packit |
7cfc04 |
.I /proc/sys/net/ipv4/ip_local_port_range
|
|
Packit |
7cfc04 |
in
|
|
Packit |
7cfc04 |
.BR ip (7).
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EAFNOSUPPORT
|
|
Packit |
7cfc04 |
The passed address didn't have the correct address family in its
|
|
Packit |
7cfc04 |
.I sa_family
|
|
Packit |
7cfc04 |
field.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EAGAIN
|
|
Packit |
7cfc04 |
Insufficient entries in the routing cache.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EALREADY
|
|
Packit |
7cfc04 |
The socket is nonblocking and a previous connection attempt has not yet
|
|
Packit |
7cfc04 |
been completed.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EBADF
|
|
Packit |
7cfc04 |
.I sockfd
|
|
Packit |
7cfc04 |
is not a valid open file descriptor.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ECONNREFUSED
|
|
Packit |
7cfc04 |
A
|
|
Packit |
7cfc04 |
.BR connect ()
|
|
Packit |
7cfc04 |
on a stream socket found no one listening on the remote address.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EFAULT
|
|
Packit |
7cfc04 |
The socket structure address is outside the user's address space.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINPROGRESS
|
|
Packit |
7cfc04 |
The socket is nonblocking and the connection cannot be completed
|
|
Packit |
7cfc04 |
immediately.
|
|
Packit |
7cfc04 |
It is possible to
|
|
Packit |
7cfc04 |
.BR select (2)
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR poll (2)
|
|
Packit |
7cfc04 |
for completion by selecting the socket for writing.
|
|
Packit |
7cfc04 |
After
|
|
Packit |
7cfc04 |
.BR select (2)
|
|
Packit |
7cfc04 |
indicates writability, use
|
|
Packit |
7cfc04 |
.BR getsockopt (2)
|
|
Packit |
7cfc04 |
to read the
|
|
Packit |
7cfc04 |
.B SO_ERROR
|
|
Packit |
7cfc04 |
option at level
|
|
Packit |
7cfc04 |
.B SOL_SOCKET
|
|
Packit |
7cfc04 |
to determine whether
|
|
Packit |
7cfc04 |
.BR connect ()
|
|
Packit |
7cfc04 |
completed successfully
|
|
Packit |
7cfc04 |
.RB ( SO_ERROR
|
|
Packit |
7cfc04 |
is zero) or unsuccessfully
|
|
Packit |
7cfc04 |
.RB ( SO_ERROR
|
|
Packit |
7cfc04 |
is one of the usual error codes listed here,
|
|
Packit |
7cfc04 |
explaining the reason for the failure).
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINTR
|
|
Packit |
7cfc04 |
The system call was interrupted by a signal that was caught; see
|
|
Packit |
7cfc04 |
.BR signal (7).
|
|
Packit |
7cfc04 |
.\" For TCP, the connection will complete asynchronously.
|
|
Packit |
7cfc04 |
.\" See http://lkml.org/lkml/2005/7/12/254
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EISCONN
|
|
Packit |
7cfc04 |
The socket is already connected.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ENETUNREACH
|
|
Packit |
7cfc04 |
Network is unreachable.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ENOTSOCK
|
|
Packit |
7cfc04 |
The file descriptor
|
|
Packit |
7cfc04 |
.I sockfd
|
|
Packit |
7cfc04 |
does not refer to a socket.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EPROTOTYPE
|
|
Packit |
7cfc04 |
The socket type does not support the requested communications protocol.
|
|
Packit |
7cfc04 |
This error can occur, for example,
|
|
Packit |
7cfc04 |
on an attempt to connect a UNIX domain datagram socket to a stream socket.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ETIMEDOUT
|
|
Packit |
7cfc04 |
Timeout while attempting connection.
|
|
Packit |
7cfc04 |
The server may be too
|
|
Packit |
7cfc04 |
busy to accept new connections.
|
|
Packit |
7cfc04 |
Note that for IP sockets the timeout may
|
|
Packit |
7cfc04 |
be very long when syncookies are enabled on the server.
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD,
|
|
Packit |
7cfc04 |
.RB (connect ()
|
|
Packit |
7cfc04 |
first appeared in 4.2BSD).
|
|
Packit |
7cfc04 |
.\" SVr4 documents the additional
|
|
Packit |
7cfc04 |
.\" general error codes
|
|
Packit |
7cfc04 |
.\" .BR EADDRNOTAVAIL ,
|
|
Packit |
7cfc04 |
.\" .BR EINVAL ,
|
|
Packit |
7cfc04 |
.\" .BR EAFNOSUPPORT ,
|
|
Packit |
7cfc04 |
.\" .BR EALREADY ,
|
|
Packit |
7cfc04 |
.\" .BR EINTR ,
|
|
Packit |
7cfc04 |
.\" .BR EPROTOTYPE ,
|
|
Packit |
7cfc04 |
.\" and
|
|
Packit |
7cfc04 |
.\" .BR ENOSR .
|
|
Packit |
7cfc04 |
.\" It also
|
|
Packit |
7cfc04 |
.\" documents many additional error conditions not described here.
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
POSIX.1 does not require the inclusion of
|
|
Packit |
7cfc04 |
.IR <sys/types.h> ,
|
|
Packit |
7cfc04 |
and this header file is not required on Linux.
|
|
Packit |
7cfc04 |
However, some historical (BSD) implementations required this header
|
|
Packit |
7cfc04 |
file, and portable applications are probably wise to include it.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
For background on the
|
|
Packit |
7cfc04 |
.I socklen_t
|
|
Packit |
7cfc04 |
type, see
|
|
Packit |
7cfc04 |
.BR accept (2).
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.BR connect ()
|
|
Packit |
7cfc04 |
fails, consider the state of the socket as unspecified.
|
|
Packit |
7cfc04 |
Portable applications should close the socket and create a new one for
|
|
Packit |
7cfc04 |
reconnecting.
|
|
Packit |
7cfc04 |
.SH EXAMPLE
|
|
Packit |
7cfc04 |
An example of the use of
|
|
Packit |
7cfc04 |
.BR connect ()
|
|
Packit |
7cfc04 |
is shown in
|
|
Packit |
7cfc04 |
.BR getaddrinfo (3).
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR accept (2),
|
|
Packit |
7cfc04 |
.BR bind (2),
|
|
Packit |
7cfc04 |
.BR getsockname (2),
|
|
Packit |
7cfc04 |
.BR listen (2),
|
|
Packit |
7cfc04 |
.BR socket (2),
|
|
Packit |
7cfc04 |
.BR path_resolution (7)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|