TutSocketCreateServerLocal

Name

TutSocketCreateServerLocal — create the server side of a local socket

Synopsis

T_INT4 TutSocketCreateServerLocal(file_name) 
T_STR file_name; 

Arguments

file_name — name of file to associate with this socket

Return Values

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

Diagnostics

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

Description

TutSocketCreateServerLocal is a convenience function that creates a local (UNIX-domain) socket, binds an address to it, and listens for new connections on the socket. 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).

To ensure that the socket address (the file name) is not already in use, TutSocketCreateServerLocal first tries to connect to the local socket specified by file_name. If the connection succeeds, then the address is already in use, and TutSocketCreateServerLocal returns FALSE.

Caution

TutSocketCreateServerLocal arranges for SIGPIPE signals to be ignored.

On UNIX, TutSocketCreateServerLocal 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, TutSocketCreateServerLocal requires TMPMBX privilege.

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

See Also

TutGetSocketDir, TutSocketAccept, TutSocketCreateClientLocal

Examples

This example creates a socket connection to a client, receives an integer from the client, adds one to that integer, and then sends the integer back to the client:

int main(argc, argv) 
int argc; 
char **argv; 
{ 
  T_INT4 server_fd;    /* socket for accepting new connections */ 
  T_INT4 socket_fd;    /* socket connection to client */ 
  T_INT4 a_number;     /* number read from and written to client */ 
  T_INT4 status;       /* status code */ 
 
  /* create socket to accept connections on */ 
  server_fd = TutSocketCreateServerLocal("file.sock"); 
  if (server_fd == -1) { 
    TutOut("TutSocketCreateServerLocal failed.\n"); 
    TutExit(T_EXIT_FAILURE); 
  }  
 
  /* make sure client connects within 30 seconds */ 
  if (!TutSocketCheck(server_fd, T_IO_CHECK_READ, 30.0)) { 
    TutOut("Client did not connect in time.\n"); 
    TutExit(T_EXIT_FAILURE); 
  }  
 
  /* create connection to client */ 
  socket_fd = TutSocketAccept(server_fd); 
  if (socket_fd == -1) { 
    TutOut("TutSocketAccept failed.\n"); 
    TutExit(T_EXIT_FAILURE); 
  }  
 
  /* close original socket: we don’t need it anymore */ 
  status = T_C_CLOSESOCKET(server_fd); 
  if (status != 0) { 
    TutPerror("close"); 
  }  
 
  /* read an integer from our client */ 
  status = TutSocketRecvAll(socket_fd, (char *)&a_number, 
                                sizeof(a_number), 0); 
  if (status != sizeof(a_number)) { 
    TutOut("only read %d/%d bytes from client.\n", 
           status, sizeof(a_number)); 
    TutExit(T_EXIT_FAILURE); 
  }  
  TutOut("Number from client is %d.\n", a_number); 
 
  /* increment the integer and send it back to the client */ 
  a_number++; 
  TutOut("Sending number %d back to client.\n", a_number); 
  status = T_C_SEND(socket_fd, (char *)&a_number,  
                      sizeof(a_number), 0);   
  if (status != sizeof(a_number)) { 
    TutOut("only wrote %d/%d bytes from client.\n", 
            status, sizeof(a_number)); 
    TutExit(T_EXIT_FAILURE); 
  }  
 
  TutExit(T_EXIT_SUCCESS); 
} /* main */