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

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 ]