TutSocketCreateClientLocal

Name

TutSocketCreateClientLocal — create the client side of a local socket

Synopsis

T_INT4 TutSocketCreateClientLocal(file_name) 
T_STR file_name; 

Arguments

file_name — file name server socket is associated with

Return Values

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

Diagnostics

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

Description

TutSocketCreateClientLocal is a convenience function that creates a local (UNIX-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.

Local sockets are bidirectional and have a file name associated with them. 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).

Caution

TutSocketCreateClientLocal arranges for SIGPIPE signals to be ignored.

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

The socket file file_name is always placed in the directory returned by TutGetSocketDir.

On OpenVMS, TutSocketCreateClientLocal requires TMPMBX privilege.

On Windows, TutSocketCreateClientLocal is a stub function that always fails.

See Also

TutGetSocketDir, TutSocketCreateServerLocal

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_INT4 socket_fd;  /* socket connection to server */ 
  T_INT4 a_number;   /* number written to and read from server */ 
  T_INT4 status;     /* status code */ 
 
  socket_fd = TutSocketCreateClientLocal("file.sock"); 
  if (socket_fd == -1) { 
    TutOut("TutSocketCreateClientLocal 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 */