connect Subroutine

Edit online

Purpose

Connects two sockets.

Library

Standard C Library (libc.a)

Syntax

#include <sys/socket.h>

int connect ( Socket, Name, NameLength )  
int Socket; 
const struct sockaddr *Name;
socklen_t NameLength;

Description

The connect subroutine requests a connection between two sockets. The kernel sets up the communication link between the sockets; both sockets must use the same address format and protocol.

If a connect subroutine is issued on an unbound socket or a partially bound socket, the system automatically binds the socket. A partially bound socket is a socket that is assigned a port number but no IP address. The connect subroutine can be used to connect a socket to itself. A socket can be connected to itself, by binding a socket to a local port (by using bind subroutine) and then connecting it to the same port with a local IP address (by using connect subroutine).

The connect subroutine performs a different action for each of the following two types of initiating sockets:

  • If the initiating socket is SOCK_DGRAM, the connect subroutine establishes the peer address. The peer address identifies the socket where all datagrams are sent on subsequent send subroutines. No connections are made by this connect subroutine. If the UDP socket is receiving datagrams when the connect subroutine is called, the subroutine changes the IP address, preventing the socket from receiving datagram packets based on the previous address.
  • If the initiating socket is SOCK_STREAM or SOCK_CONN_DGRAM, the connect subroutine attempts to make a connection to the socket specified by the Name parameter. Each communication space interprets the Name parameter differently. For SOCK_CONN_DGRAM socket type and ATM protocol, the remote station might modify some of the ATM parameters. If the remote station modifies the ATM parameters, applications might query new values of ATM parameters by using the appropriate socket options.
  • For a UNIX domain socket, a connect call succeeds only if the process that calls connect subroutine has read and write permissions on the socket file that is created by the bind call. Permissions are determined by the umask value, which is the value of the process that created the file.

Parameters

Item Description
Socket Specifies the unique name of the socket.
Name Specifies the address of the target socket that forms the other end of the communication line
NameLength Specifies the length of the address structure.

Return Values

Upon successful completion, the connect subroutine returns a value of 0.

If the connect subroutine is unsuccessful, the system handler performs the following functions:

  • Returns a value of -1 to the calling program.
  • Moves an error code, indicating the specific error, into the errno global variable.

Error Codes

The connect subroutine is unsuccessful if any of the following errors occurs:

Value Description
EADDRINUSE The specified address is already in use. This error also occurs if the SO_REUSEADDR socket option was set and the local address (whether specified or selected by the system) is already in use.
EADDRNOTAVAIL The specified address is not available from the local machine.
EAFNOSUPPORT The addresses in the specified address family cannot be used with this socket.
EALREADY The socket is specified with the O_NONBLOCK or O_NDLAY flag, and a previous connection attempt is not yet completed.
EINTR The attempt to establish a connection was interrupted by delivery of a signal that was caught. The connection is established asynchronously.
EACCES Search permission is denied on a component of the path prefix or write access to the named socket is denied.
ENOBUFS The system ran out of memory for an internal data structure.
EOPNOTSUPP The socket that is referenced by Socket parameter does not support connect.
EWOULDBLOCK The range that is allocated for TCP/UDP ephemeral ports is exhausted.
EBADF The Socket parameter is not valid.
ECONNREFUSED The attempt to connect was rejected.
EFAULT The Address parameter is not in a writable part of the user address space.
EINPROGRESS The socket is marked as nonblocking. The connection cannot be immediately completed. The application program can select the socket for writing during the connection process.
EINVAL This error occurs in the following cases:
  • The specified path name contains a character with the high-order bit set.
  • If the previous call to the connect subroutine fails. In such case, close and re-open the socket that is in error state and reattempt the call to the connect subroutine.
EISCONN The socket is already connected.
ENETDOWN The specified physical network is down.
ENETUNREACH No route to the network or host is present.
ENOSPC There is no space that is left on a device or system table.
ENOTCONN The socket might not be connected.
ENOTSOCK The Socket parameter refers to a file, not a socket.
ETIMEDOUT The establishment of a connection timed out before a connection was made.
EPROTOTYPE The specified address has a different type from the socket that is bound to the specified peer address.
ELOOP Too many symbolic links were encountered in converting the path name in the address.
ENOENT A component of the path name does not name an existing file or the path name is an empty string.
ENOTDIR A component of the path prefix of the path name in the address is not a directory.

Examples

The following program fragment illustrates the use of the connect subroutine by a client to initiate a connection to a server's socket.

struct sockaddr_un server;
.
.
.
connect(s,(struct sockaddr*)&server, sun_len(&server));