connect: Request a connection to a remote host

The connect socket function requests a connection to a remote host.

Last updated

Added for PUT00

Format

#include  <sys/socket.h>
int       connect(int s,
                  struct sockaddr *name,
                  int namelen);
s
The socket descriptor. The s parameter is the socket used to originate the connection request.
name
Pointer to a sockaddr structure that contains the address of the socket to which a connection will be attempted.
namelen
Size, in bytes, of the sockaddr structure pointed to by name.

Normal return

Return code 0 indicates that the function was successful.

Error return

A return code equal to -1 indicates an error. You can get the specific error code by calling sock_errno. See z/TPF Transmission Control Protocol/Internet Protocol for more information about socket errors.
E1052STATE
The socket was closed because the system was in or cycling down to 1052 state.
ESYSTEMERROR
A system error has occurred and closed the socket.
SOCADDRINUSE
A socket with the same protocol, local and remote IP addresses, and local and remote ports already exists.
SOCADDRNOTAVAIL
The calling host cannot reach the specified destination.
SOCAFNOSUPPORT
The address family is not supported.
SOCALREADY
Socket s is marked nonblocking and a previous connection attempt has not completed.
SOCCONNREFUSED
The connection request was rejected by the destination host. This error code can also occur if the TCP connection limit has been reached for the specified server application.
SOCFAULT
Using name and namelen would result in an attempt to copy the address into a protected address space.
SOCINPROGRESS
Socket s is marked nonblocking, and the connection cannot be completed immediately. The SOCINPROGRESS value does not indicate an error condition.
SOCINVAL
The namelen parameter is not a valid length.
SOCISCONN
Socket s is already connected.
SOCNETUNREACH
An ICMP message was received on this socket (in response to sent data) indicating that the destination IP address and/or destination port are not reachable.
SOCNOBUFS
There is not enough buffer space to start a new connection.
SOCNOTSOCK
The s parameter is not a valid socket descriptor.
SOCTIMEDOUT
A timeout occurred before the connection was made.

Programming considerations

  • For stream sockets, the connect call attempts to establish a connection between two sockets. For UDP sockets, the connect function specifies the peer for a socket.
  • The connect function performs two tasks when called for a stream socket. First, it completes the binding necessary for a stream socket (if it has not been previously bound using the bind function). Second, it attempts to make a connection to another socket.
  • The connect function on a stream socket is used by the client application to establish a connection to a server. The server must have a passive open binding. If the server is using sockets, the server must successfully call bind and listen before a connection can be accepted by the server with accept. Otherwise, connect returns -1 and sets the error code to SOCCONNREFUSED.
  • If s is in blocking mode, the connect function blocks the caller until the connection is set up, or until an error is received. If the socket is in nonblocking mode, connect returns -1 with the error code set to SOCINPROGRESS if the connection can be started (no other errors occurred). For this condition, this return code does not indicate an error condition. The caller can test the completion of the connection setup by calling the select for write function and testing for the ability to write to the socket.
  • When called for a datagram or raw socket, the connect function specifies the peer with which this socket is associated. This lets the application use data transfer calls reserved for sockets that are in the connected state. For this condition, the send and recvfrom functions are available. Stream sockets can call the connect function only once, but datagram sockets can call the connect function multiple times to change their association. Datagram sockets can end their association by connecting to an incorrect address such as the null address (all fields zeroed).
  • The receive timeout value (the SO_RCVTIMEO option on the setsockopt function) determines how long to wait for the connection to be established before the connect function times out. If you don't specify a value for SO_RCVTIMEO, the default value of 75 seconds is used.
  • If the name parameter has an IP address that is set to 0, the system uses the loopback IP address (127.0.0.1).

Examples

The following example connects to a server application that has IP address 129.5.24.1 and port number 5001. 
#include <sys/socket.h>
⋮
int rc;
int client_sock;
struct sockaddr_in server_addr;
⋮
memset(&server_addr, 0,sizeof(server_addr));
server_addr.sin_family      = AF_INET;
server_addr.sin_port        = 5001;
server_addr.sin_addr.s_addr = inet_addr("129.5.24.1");
rc = connect(client_sock, (struct sockaddr *) &server_addr,
             sizeof(server_addr));

Related information

See z/TPF Transmission Control Protocol/Internet Protocol for information about z/TPF TCP/IP support.