summaryrefslogtreecommitdiffstats
path: root/man/man2/connect.2
diff options
context:
space:
mode:
Diffstat (limited to 'man/man2/connect.2')
-rw-r--r--man/man2/connect.2253
1 files changed, 253 insertions, 0 deletions
diff --git a/man/man2/connect.2 b/man/man2/connect.2
new file mode 100644
index 0000000..b35d991
--- /dev/null
+++ b/man/man2/connect.2
@@ -0,0 +1,253 @@
+.\" 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.
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\"
+.\" 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.
+.\"
+.\" SPDX-License-Identifier: BSD-4-Clause-UC
+.\"
+.\" 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 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+connect \- initiate a connection on a socket
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/socket.h>
+.P
+.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.
+.P
+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 .
+.P
+Some protocol sockets (e.g., UNIX domain stream sockets)
+may successfully
+.BR connect ()
+only once.
+.P
+Some protocol sockets
+(e.g., datagram sockets in the UNIX and Internet domains)
+may use
+.BR connect ()
+multiple times to change their association.
+.P
+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 since Linux 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
+.B EACCES
+.TQ
+.B 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 EACCES
+It 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).
+.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
+.B 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 STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001, 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
+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)