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)

 #define _XOPEN_SOURCE 520
 #include <sys/socket.h>

 int connect(int socket_descriptor,
             const struct sockaddr *destination_address,
             socklen_t 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.

There are two versions of the API, as shown above. The base IBM^® i API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX^® 98 programming interface specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro.

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>.

The BSD 4.3 structure is:

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

The BSD 4.4/UNIX 98 compatible structure is:

      typedef uchar   sa_family_t;

      struct sockaddr {
         uint8_t     sa_len;
         sa_family_t sa_family;
         char        sa_data[14];
      };

The BSD 4.4 sa_len field is the length of the address. 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.

Authorities

When the address type of the socket identified by the socket_descriptor is AF_INET and is running IP over SNA, the thread must have retrieve, insert, delete, and update authority to the APPC device. When the thread does not have this level of authority, then an errno of EACCES is returned.

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.

[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).
[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.
[EADDRNOTAVAIL]	Address not available. This error code is returned if the socket_descriptor parameter points to a socket with an address family of AF_INET or AF_INET6 and either a port was not available or a route to the address specified by the destination_address parameter could not be found.
[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.
[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_INET6 address families.
[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 or AF_INET6 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_UNIX_CCSID, 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_INET6), 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. The socket_descriptor points to a socket with an address family of AF_UNIX_CCSID, and the CCSID specified in sunc_qlg in the sockaddr_unc structure (pointed to by local_address) cannot be converted to the current default CCSID for integrated file system path names. The socket_descriptor points to a socket with an address family of AF_UNIX_CCSID, and there was an incomplete character or shift state sequence at the end of sunc_path in the sockaddr_unc structure (pointed to by local_address). The socket_descriptor points to a socket with an address family of AF_UNIX_CCSID, and the sockaddr_unc structure (pointed to by local_address) was not valid: The sunc_format was not set to SO_UNC_DEFAULT or SO_UNC_USE_QLG. The sunc_zero was not initialized to zeros. The sunc_format field was set to SO_UNC_USE_QLG and the sunc_qlg structure was not valid: The path type was less than 0 or greater than 3. The path length was less than 0 or out of bounds. For example, a single byte path name was greater than 126 bytes or a double byte path name was greater than 252 bytes. A reserved field was not initialized to zeros.
[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 or AF_UNIX_CCSID address family.
[ENAMETOOLONG]	File name too long. This error code is only returned on sockets that use the AF_UNIX or AF_UNIX_CCSID address family.
[ENETDOWN]	The network is not currently available.
[ENETUNREACH]	Cannot reach the destination network. This error code is returned for sockets that use the AF_INET or AF_INET6 address families, the address specified by the destination_address parameter requires the use of a router, and the socket option SO_DONTROUTE is currently set on.
[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 or AF_UNIX_CCSID address family.
[ENOSYS]	Function not implemented. This error code is only returned on sockets that use the AF_UNIX and AF_UNIX_CCSID address families.
[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 or AF_UNIX_CCSID address family.
[EOPNOTSUPP]	Operation not supported. connect() is not allowed on a passive socket (a socket for which a listen() has been done).
[EPERM]	The operation is not permitted. A user exit program registered for the exit point, QIBM_QSO_CONNECT, has rejected the outgoing connection.
[EPROTOTYPE]	The socket type or protocols are not compatible. This error code is only returned on sockets that use the AF_UNIX or AF_UNIX_CCSID 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().
[EUNKNOWN]	Unknown system state.
[EUNATCH]	The protocol required to support the specified address family is not available at this time.
[EPROTO]	An underlying protocol error has occurred.

Error Messages

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 or AF_INET6 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 or AF_INET6 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 or AF_INET6 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 or AF_INET6, 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(). The IPV6_ADDR_PREFERECES socket option flags set on setsockopt() will be taken into consideration when binding to the source address.
   
   
6. For sockets with an address family of AF_INET, the following is applicable:
   • 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]).
   
   
7. For sockets with an address family of AF_UNIX or AF_UNIX_CCSID, 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.
     
     
   • For AF_UNIX, the path name is assumed to be in the default coded character set identifier (CCSID) currently in effect for the job. For AF_UNIX_CCSID, the path name is assumed to be in the format and coded character set identifier (CCSID) specified in the sockaddr_unc (pointed to by local_address).
   
   
8. When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the connect() API is mapped to qso_connect98().

9. A user exit point, QIBM_QSO_CONNECT, exists to optionally allow or deny outgoing connections based on the return code from the registered user exit program. For more information refer to Sockets connect() API Exit Program.

Related Information

• _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface
  
  
• fcntl()--Perform File Control Command
  
  
• ioctl()--Perform I/O Control Request
  
  
• bind()--Set Local Address for Socket
  
  
• accept()--Wait for Connection Request and Make Connection
  
  
• sendto()--Send Data
  
  
• sendmsg()--Send Data or Descriptors or Both

[ Back to top | UNIX-Type APIs | APIs by category ]