connect()--Establish Connection or Destination Address

#include <sys/types.h>
#include <sys/socket.h>

int connect(int socket_descriptor,
            struct sockaddr *destination_address,
            int address_length)

The connect() function is used to establish a connection on a connection-oriented socket or establish the destination address on a connectionless socket.

Parameters

socket_descriptor

(Input) The descriptor of the socket that is to be connected.

destination_address

(Input) A pointer to a buffer of type struct sockaddr that contains the destination address to which the socket is to be bound. The structure sockaddr is defined in <sys/socket.h>.

      struct sockaddr {
         u_short sa_family;
         char    sa_data[14];
      };

The sa_family field identifies the address family to which the address belongs, and sa_data is the address whose format is dependent on the address family.

address_length

(Input) The length of the destination_address.

Return Value

connect() returns an integer. Possible values are:

• -1 (unsuccessful)

• 0 (successful)

Error Conditions

When a connect() fails, errno can be set to one of the following. For additional debugging information, see Debugging IP over SNA Configurations and Appendix E, IPX Problem Analysis in the Internetwork Packet Exchange (IPX) Support book.

[EACCES]

Permission denied.

This error code indicates one of the following:

• The process does not have the appropriate privileges to connect to the address pointed to by the destination_address parameter.

• The socket pointed to by socket_descriptor is using a connection-oriented transport service, and the destination_address parameter specifies a TCP/IP limited broadcast address (internet address of all ones).

• The socket_descriptor parameter points to a socket with an address family of AF_NS, uses a connection-oriented transport service, and specifies an address that contains 0xFF for each byte of the host address.

[EADDRINUSE]

Address already in use.

This error code indicates one of the following:

• The socket_descriptor parameter points to a connection-oriented socket that has been bound to a local address that contained no wildcard values, and the destination_address parameter specified an address that matched the bound address.

• The socket_descriptor parameter points to a socket that has been bound to a local address that contained no wildcard values, and the destination_address parameter (also containing no wildcard values) specified an address that would have resulted in a connection with a non-unique association.

  Note: Sockets with an address family of AF_NS can have non-unique associations of local and remote addresses. This is because the underlying transport protocol utilizes a connection identifier number which is unique for each socket, regardless of the address associated with the socket.

[EADDRNOTAVAIL]

Address not available.

This error code indicates one of the following:

• The socket_descriptor parameter points to a socket with an address family of AF_INET and either a port was not available or a route to the address specified by the destination_address parameter could not be found.

• The socket_descriptor parameter points to a socket with an address family of AF_NS, and either a port was not available or a connection identifier number could not be obtained. There are a maximum of 65 535 unique connection IDs available on a system. However, the number of connection IDs may be restricted by the SPX maximum sessions parameter of the active IPX description. You can determine the SPX maximum sessions by using the Display IPX Description (DSPIPXD) command.

[EAFNOSUPPORT]

The type of socket is not supported in this protocol family.

The address family specified in the address structure pointed to by destination_address parameter cannot be used with the socket pointed to by the socket_descriptor parameter.

[EALREADY]

Operation already in progress.

A previous connect() function had already been issued for the socket pointed to by the socket_descriptor parameter, and has yet to be completed. This error code is returned only on sockets that use a connection-oriented transport service.

[EBADF]

Descriptor not valid.

[ECONNREFUSED]

The destination socket refused an attempted connect operation.

This error occurs when there is no application that is bound to the address specified by the destination_address parameter.

Note: For sockets with address family AF_NS, this error condition is not reported if the address specified by destination_address is not a loopback address.

[EFAULT]

Bad address.

The system detected an address which was not valid while attempting to access the destination_address parameter.

[EHOSTUNREACH]

A route to the remote host is not available.

This error code is returned on sockets that use the AF_INET and AF_TELEPHONY address families.

For address family AF_TELEPHONY sockets, this error indicates that the default connection list entry was not available.

[EINPROGRESS]

Operation in progress.

The socket_descriptor parameter points to a socket that is marked as nonblocking and the connection could not be completed immediately. This error code is returned only on sockets that use a connection-oriented transport service.

[EINTR]

Interrupted function call.

[EINVAL]

Parameter not valid.

This error code indicates one of the following:

• The address_length parameter specifies a length that is negative or not valid for the address family.

• The AF_INET socket is of type SOCK_STREAM, and a previous connect() has already completed unsuccessfully. Only one connection attempt is allowed on a connection-oriented socket.

  Note: For sockets that have an address family of AF_UNIX or AF_NS if a connect() fails, a subsequent connect() is allowed, even if the transport service being used is connection-oriented.

• connect() cannot be issued on the socket pointed to by the socket_descriptor parameter because the socket is using a connection-oriented transport service (with an address family of AF_INET or AF_NS), and a shutdown() that disabled the sending of data was previously issued.

• The destination address pointed to by the destination_address parameter specified an address that was not valid.

[EIO]

Input/output error.

[EISCONN]

A connection has already been established.

This error code is returned only on sockets that use a connection-oriented transport service.

[ELOOP]

A loop exists in symbolic links encountered during pathname resolution.

This error code is only returned on sockets that use the AF_UNIX address family.

[ENAMETOOLONG]

File name too long.

This error code is only returned on sockets that use the AF_UNIX address family.

[ENETDOWN]

The network is not currently available.

[ENETUNREACH]

Cannot reach the destination network.

This error code indicates the following:

• For sockets that use the AF_INET address family, the address specified by the destination_address parameter requires the use of a router, and the socket option SO_DONTROUTE is currently set on.

• For sockets that use an address family of AF_NS, the address specified by the destination_address parameter either requires the use of a router and the socket option SO_DONTROUTE is currently set on, or the address references a network for which a route cannot be found.

[ENOBUFS]

There is not enough buffer space for the requested operation.

[ENOENT]

No such file or directory.

This error code is only returned on sockets that use the AF_UNIX address family.

[ENOSYS]

Function not implemented.

This error code is only returned on sockets that use the AF_UNIX address family.

[ENOTDIR]

Not a directory.

[ENOTSOCK]

The specified descriptor does not reference a socket.

This error code is only returned on sockets that use the AF_UNIX address family.

[EOPNOTSUPP]

Operation not supported.

connect() is not allowed on a passive socket (a socket for which a listen() has been done).

[EPROTOTYPE]

The socket type or protocols are not compatible.

This error code is only returned on sockets that use the AF_UNIX address family.

[ETIMEDOUT]

A remote host did not respond within the timeout period.

This error code is returned when connection establishment times out. No connection is established. A possible cause may be that the partner application is bound to the address specified by the destination_address parameter, but the partner application has not yet issued a listen().

Note: For sockets with an address family of AF_NS, this error may also be reported when there is no application bound to the address specified by the destination_address parameter.

[EUNKNOWN]

Unknown system state.

[EUNATCH]

The protocol required to support the specified address family is not available at this time.

Error Messages

CPE3418 E

Possible APAR condition or hardware failure.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.

CPFA081 E

Unable to set return value or error code.

Usage Notes

1. connect() establishes an end-to-end connection. It can only be issued once on sockets that have an address family of AF_INET and are of type SOCK_STREAM. (If the connect() fails to successfully establish the connection, you must close the socket and create a new socket if you wish to try to establish a connection again.) For sockets of other address families that are connection-oriented, you may simply try the connect() again to the same or to a new address. connect() can be issued on sockets of type SOCK_DGRAM and SOCK_RAW multiple times. Each time connect() is issued, it changes the destination address from which packets may be received and to which packets may be sent.

   Note: Issuing connect() on sockets of type SOCK_DGRAM and SOCK_RAW is not recommended because of dynamic route reassignment (picking a new route when a route that was previously used is no longer available). When this reassignment occurs, the next packet from the partner program can be received from a different IP address than the address your application specified on the connect(). This results in the data being discarded.

2. When a connect() is issued successfully on sockets with an address family of AF_INET and type of SOCK_DGRAM, errors relating to the unsuccessful delivery of outgoing packets may be received as errno values. For example, assume an application has issued the connect() for a destination_address at which no server is currently bound for the port specified in destination_address, and the application sends several packets to that destination_address. Eventually, one of the application output functions (for example, send()) will receive an error [ECONNREFUSED]. If the application had not issued the connect(), this diagnostic information would have been discarded.

3. A connectionless transport socket for which a connect() has been issued can be disconnected by either setting the destination_address parameter to NULL or setting the address_length parameter to zero, and issuing another connect().

4. For sockets that use a connection-oriented transport service and an address family of AF_INET there is a notion of a directed connect. A directed connect allows two socket endpoints (socket A and socket B) to be connected without having a passive socket to accept an incoming connection request. The idea is for both sockets to bind to addresses. Socket A then issues a connect() specifying the address that socket B is bound to, and socket B issues a connect() specifying the address that socket A is bound to. At this point sockets A and B are connected, and data transfer between the sockets can now take place.

5. For sockets with an address family of AF_INET, the following is applicable:

   • For sockets of type SOCK_STREAM or SOCK_DGRAM, a local port number is implicitly assigned to the socket if the connect() is issued without previously issuing a bind().

   • A local port number is implicitly assigned to the socket if the connect() is issued without previously issuing a bind().

   • If the destination address has an IP address that is set to zero, the system selects an appropriate destination IP address using the following algorithm:

     • If the socket is bound to an IP address of zero, a loopback address is used. If a loopback interface is not configured (or the associated interface is not active), the address of the next available interface that is active is used. Otherwise, the destination IP address is not changed (and results in an error on the connect()).

     • If the socket is bound to a nonzero IP address, then the IP address that the socket is bound to is used.

   • If the destination address has an internet IP address that is set to INADDR_BROADCAST (hex 0xFFFFFFFF), the system selects an appropriate destination IP address using the following algorithm:

     • If the socket is bound to an IP address of zero and:

       • It is using a connectionless transport service, then the first active interface found that supports broadcast frames is used by the networking software.

       • It is using a connection-oriented transport service, an error is returned ([EACCES]).

     • If the socket is bound to a nonzero IP address and is using a connectionless transport service and:

       • The address that the socket is bound to denotes an interface that supports broadcast frames (for example, not a loopback address), then the limited broadcast address of the IP address that the socket is bound to is used.

       • The address that the socket is bound to is a loopback address, an error is returned ([EINVAL]).

     • If the socket is bound to a nonzero IP address and it is using a connection-oriented transport service, an error is returned ([EACCES]).

   • For sockets with an address family of AF_NS, the following is applicable:

     • A local port number is implicitly assigned to the socket if the connect() is issued without previously issuing a bind().

     • To connect to an application on the same system, the network and the host portion of the address specified by the destination_address parameter should be zeros.

     • If the network portion of the address specified in the destination_address parameter is zero, and the host portion of the address is six bytes of 0xFF, the connect is rejected with [EINVAL].

     • If the address specified by the destination_address parameter specifies a network portion that is not zero and a host portion that has 0xFF for all six bytes, the following occurs:

       • connect() returns [EACCES] for sockets of type SOCK_STREAM or SOCK_SEQPACKET.

       • connect() completes successfully for sockets of type SOCK_DGRAM and subsequent output operations on the socket result in the data being broadcast to all hosts on the specified network, if the SO_BROADCAST socket option is on.

6. For sockets with an address family of AF_UNIX, the following is applicable:

   • There is no implicit binding of an address to the socket. The socket is unnamed if the connect() is issued without previously issuing a bind().

   • The process must have write access to the destination address and search permission along all the components of the path.

   • The path name is assumed to be in the default coded character set identifier (CCSID) currently in effect for the job.

7. For sockets with an address family of AF_TELEPHONY, the following is applicable:

   • If the connect() is issued without previously issuing a bind(), the socket is implicitly bound to a local address of TELADDR_ANY.

   • If the destination address is specified as TELADDR_ANY, the remote number contained in the out connection list entry of the connection list associated with the socket's first device will be used for the connect().

Related Information

• fcntl()--Retrieve or Change Descriptor Attributes

• ioctl()--Change Descriptor Attributes

• bind()--Set Local Address for Socket

• accept()--Wait for Connection Request and Make Connection

• sendto()--Send Data

• sendmsg()--Send Data or Descriptors or Both