TutSocketCreateClientTcp

Name

TutSocketCreateClientTcp — create the client side of a TCP/IP socket

Synopsis

T_INT4 TutSocketCreateClientTcp(node_name, port_num) 
T_STR node_name; 
T_INT4 port_num; 

Arguments

node_name — name of TCP/IP node the server socket is on

port_num — port number TCP/IP server socket is associated with

Return Values

Non-negative socket file descriptor if successful, -1 otherwise.

Diagnostics

If TutSocketCreateClientTcp fails, it returns -1 and sets the global SmartSockets error number to one of:

Description

TutSocketCreateClientTcp is a convenience function that creates a TCP/IP (Internet-domain) socket and connects to a server socket that has already been created. Once both ends of the socket are connected, data may be read from the socket with recv and written to the socket with send. The socket can be checked for input with select.

TCP/IP sockets are bidirectional and have a TCP/IP port number associated with them. node_name specifies the name of the TCP/IP node where the server socket exists, and port_num is used to specify this TCP/IP port number. node_name can be a string node name, such as my_node or my_node.my_domain.com, or an IP address of the form d.d.d.d, such as 192.9.200.33. When creating a client/server socket connection, the server side must always be created first (with sockets the client side must have something to connect to).

When making a connection to the TCP/IP server socket, the connecting process normally blocks for approximately 75 seconds if the server computer is unavailable. To overcome this default 75 second timeout, TutSocketCreateClientTcp uses the option Socket_Connect_Timeout that defaults to 5.0 seconds to determine the maximum amount of time to wait for the connection to complete. If Socket_Connect_Timeout is 0, then TutSocketCreateClientTcp uses the default blocking behavior.

TutSocketCreateClientTcp sets the socket option SO_LINGER to ensure that no data is discarded when the socket is closed.

Caution

TutSocketCreateClientTcp arranges for SIGPIPE signals to be ignored.

On UNIX, TutSocketCreateClientTcp sets the close-on-exec bit on the file descriptor, so that any child processes do not share the file descriptor.

If you are using Digital TCP/IP Services for OpenVMS (UCX), TutSocketCreateClientTcp requires NETMBX privilege. If you are using MultiNet TCP/IP on OpenVMS, TutSocketCreateClientTcp does not require any privileges.

On Windows NT, TutSocketCreateClientTcp calls SetHandleInformation with the HANDLE_FLAG_INHERIT flag set to FALSE, so that any child processes do not share the file descriptor.

See Also

TutSocketCreateServerTcp

Examples

This example creates a socket connection to a server running on the same node, sends a random integer to the server, and receives an integer back from the server:

int main(argc, argv) 
int argc; 
char **argv; 
{ 
  T_STRING node_name;  /* our node name */ 
  T_INT4 socket_fd;    /* socket connection to server */ 
  T_INT4 a_number;     /* number written to and read from server */ 
  T_INT4 status;       /* status code */ 
 
  /* create connection to server */ 
  TutGetNodeName(node_name); 
  socket_fd = TutSocketCreateClientTcp(node_name, 4242); 
  if (socket_fd == -1) { 
    TutOut("TutSocketCreateClientTcp failed.\n"); 
    TutExit(T_EXIT_FAILURE); 
  }  
  /* send an integer to our server */ 
  a_number = time(0) % 10; /* nice pseudo-random number */ 
  TutOut("Sending %d to server process.\n", a_number); 
  status = T_C_SEND(socket_fd, (char *)&a_number, 
              sizeof(a_number), 0); 
  if (status != sizeof(a_number)) { 
    TutOut("only sent %d/%d bytes to server.\n", 
            status, sizeof(a_number)); 
    TutExit(T_EXIT_FAILURE); 
  }  
  /* read an integer from our server */ 
  status = TutSocketRecvAll(socket_fd, (char *)&a_number, 
                                sizeof(a_number), 0); 
  if (status != sizeof(a_number)) { 
    TutOut("only read %d/%d bytes from server.\n", 
            status, sizeof(a_number)); 
    TutExit(T_EXIT_FAILURE); 
  }  
  TutOut("Number from server is %d.\n", a_number); 
  TutExit(T_EXIT_SUCCESS); 
} /* main */