| .\" 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. |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" 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. |
| .\" %%%LICENSE_END |
| .\" |
| .\" |
| .\" 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. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" 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. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| connect \- initiate a connection on a socket |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/socket.h> |
| .PP |
| .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. |
| .PP |
| If the socket |
| .I sockfd |
| is of type |
| .BR 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 |
| Some protocol sockets (e.g., UNIX domain stream sockets) |
| may successfully |
| .BR connect () |
| only once. |
| .PP |
| Some protocol sockets |
| (e.g., datagram sockets in the UNIX and Internet domains) |
| may use |
| .BR connect () |
| multiple times to change their association. |
| .PP |
| Some protocol sockets |
| (e.g., TCP sockets as well as datagram sockets in the UNIX and |
| Internet domains) |
| may dissolve the association by connecting to an address with the |
| .I sa_family |
| member of |
| .I sockaddr |
| set to |
| .BR AF_UNSPEC ; |
| thereafter, the socket can be connected to another address. |
| .RB ( AF_UNSPEC |
| is 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 to indicate the error. |
| .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. |
| .IP |
| .B EACCES |
| can also be returned if an SELinux policy denied a connection (for |
| example, if there is a policy saying that an HTTP proxy can only |
| connect to ports associated with HTTP servers, and the proxy tries to |
| connect to a different port). |
| dd |
| .TP |
| .B EADDRINUSE |
| Local address is already in use. |
| .TP |
| .B EADDRNOTAVAIL |
| (Internet domain sockets) |
| The socket referred to by |
| .I sockfd |
| had not previously been bound to an address and, |
| upon attempting to bind it to an ephemeral port, |
| it was determined that all port numbers in the ephemeral port range |
| are currently in use. |
| See the discussion of |
| .I /proc/sys/net/ipv4/ip_local_port_range |
| in |
| .BR ip (7). |
| .TP |
| .B EAFNOSUPPORT |
| The passed address didn't have the correct address family in its |
| .I sa_family |
| field. |
| .TP |
| .B EAGAIN |
| For nonblocking UNIX domain sockets, the socket is nonblocking, and the |
| connection cannot be completed immediately. |
| For other socket families, there are insufficient entries in the routing cache. |
| .TP |
| .B EALREADY |
| The socket is nonblocking and a previous connection attempt has not yet |
| been completed. |
| .TP |
| .B EBADF |
| .I sockfd |
| is not a valid open file descriptor. |
| .TP |
| .B ECONNREFUSED |
| A |
| .BR connect () |
| on a stream socket found 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. |
| (UNIX domain sockets failed with |
| .BR EAGAIN |
| instead.) |
| 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 |
| .I sockfd |
| does not refer to a socket. |
| .TP |
| .B EPROTOTYPE |
| The socket type does not support the requested communications protocol. |
| This error can occur, for example, |
| on an attempt to connect a UNIX domain datagram socket to a stream 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 |
| POSIX.1-2001, POSIX.1-2008, SVr4, 4.4BSD, |
| .RB (connect () |
| first appeared in 4.2BSD). |
| .\" 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 |
| For background on the |
| .I socklen_t |
| type, see |
| .BR accept (2). |
| .PP |
| If |
| .BR connect () |
| fails, consider the state of the socket as unspecified. |
| Portable applications should close the socket and create a new one for |
| reconnecting. |
| .SH EXAMPLES |
| 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), |
| .BR selinux (8) |