mirror of https://github.com/mkerrisk/man-pages
268 lines
8.2 KiB
Groff
268 lines
8.2 KiB
Groff
.\" 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.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" 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
|
|
.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.TH CONNECT 2 2008-12-03 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
connect \- initiate a connection on a socket
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.BR "#include <sys/types.h>" " /* See NOTES */"
|
|
.br
|
|
.B #include <sys/socket.h>
|
|
.sp
|
|
.BI "int connect(int " sockfd ", const struct sockaddr *" addr ,
|
|
.BI " socklen_t " addrlen );
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR connect ()
|
|
system call connects the socket referred to by the file descriptor
|
|
.I sockfd
|
|
to the address specified by
|
|
.IR addr .
|
|
The
|
|
.I addrlen
|
|
argument specifies the size of
|
|
.IR addr .
|
|
The format of the address in
|
|
.I 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
|
|
.B SOCK_DGRAM
|
|
then
|
|
.I addr
|
|
is the address to which datagrams are sent by default, and the only
|
|
address from which datagrams are received.
|
|
If the socket is of type
|
|
.B SOCK_STREAM
|
|
or
|
|
.BR SOCK_SEQPACKET ,
|
|
this call attempts to make a connection to the socket that is bound
|
|
to the address specified by
|
|
.IR addr .
|
|
.PP
|
|
Generally, connection-based protocol sockets may successfully
|
|
.BR connect ()
|
|
only once; connectionless protocol sockets may use
|
|
.BR connect ()
|
|
multiple times to change their association.
|
|
Connectionless sockets may
|
|
dissolve the association by connecting to an address with the
|
|
.I sa_family
|
|
member of
|
|
.I sockaddr
|
|
set to
|
|
.BR AF_UNSPEC
|
|
(supported on Linux since kernel 2.2).
|
|
.SH "RETURN VALUE"
|
|
If the connection or binding succeeds, zero is returned.
|
|
On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.SH ERRORS
|
|
The following are general socket errors only.
|
|
There may be other domain-specific error codes.
|
|
.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 (7).)
|
|
.TP
|
|
.BR EACCES ", " EPERM
|
|
The user tried to connect to a broadcast address without having the socket
|
|
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
|
|
The passed address didn't have the correct address family in its
|
|
.I sa_family
|
|
field.
|
|
.TP
|
|
.B EAGAIN
|
|
No more free local ports or insufficient entries in the routing cache.
|
|
For
|
|
.B AF_INET
|
|
see the description of
|
|
.I /proc/sys/net/ipv4/ip_local_port_range
|
|
.BR ip (7)
|
|
for information on how to increase the number of local ports.
|
|
.TP
|
|
.B EALREADY
|
|
The socket is nonblocking 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 nonblocking and the connection cannot be completed
|
|
immediately.
|
|
It is possible to
|
|
.BR select (2)
|
|
or
|
|
.BR poll (2)
|
|
for completion by selecting the socket for writing.
|
|
After
|
|
.BR select (2)
|
|
indicates writability, use
|
|
.BR getsockopt (2)
|
|
to read the
|
|
.B SO_ERROR
|
|
option at level
|
|
.B SOL_SOCKET
|
|
to determine whether
|
|
.BR connect ()
|
|
completed successfully
|
|
.RB ( SO_ERROR
|
|
is zero) or unsuccessfully
|
|
.RB ( SO_ERROR
|
|
is one of the usual error codes listed here,
|
|
explaining the reason for the failure).
|
|
.TP
|
|
.B EINTR
|
|
The system call was interrupted by a signal that was caught; see
|
|
.BR signal (7).
|
|
.\" For TCP, the connection will complete asynchronously.
|
|
.\" See http://lkml.org/lkml/2005/7/12/254
|
|
.TP
|
|
.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
|
|
Timeout while attempting connection.
|
|
The server may be too
|
|
busy to accept new connections.
|
|
Note that for IP sockets the timeout may
|
|
be very long when syncookies are enabled on the server.
|
|
.SH "CONFORMING TO"
|
|
SVr4, 4.4BSD, (the
|
|
.BR connect ()
|
|
function first appeared in 4.2BSD), POSIX.1-2001.
|
|
.\" SVr4 documents the additional
|
|
.\" general error codes
|
|
.\" .BR EADDRNOTAVAIL ,
|
|
.\" .BR EINVAL ,
|
|
.\" .BR EAFNOSUPPORT ,
|
|
.\" .BR EALREADY ,
|
|
.\" .BR EINTR ,
|
|
.\" .BR EPROTOTYPE ,
|
|
.\" and
|
|
.\" .BR ENOSR .
|
|
.\" It also
|
|
.\" documents many additional error conditions not described here.
|
|
.SH NOTES
|
|
POSIX.1-2001 does not require the inclusion of
|
|
.IR <sys/types.h> ,
|
|
and this header file is not required on Linux.
|
|
However, some historical (BSD) implementations required this header
|
|
file, and portable applications are probably wise to include it.
|
|
|
|
The third argument of
|
|
.BR connect ()
|
|
is in reality an
|
|
.I int
|
|
(and this is what 4.x BSD and libc4 and libc5 have).
|
|
Some POSIX confusion resulted in the present
|
|
.IR socklen_t ,
|
|
also used by glibc.
|
|
See also
|
|
.BR accept (2).
|
|
.SH EXAMPLE
|
|
An example of the use of
|
|
.BR connect ()
|
|
is shown in
|
|
.BR getaddrinfo (3).
|
|
.SH "SEE ALSO"
|
|
.BR accept (2),
|
|
.BR bind (2),
|
|
.BR getsockname (2),
|
|
.BR listen (2),
|
|
.BR socket (2),
|
|
.BR path_resolution (7)
|