TutSocketRecvTimeout

Name

TutSocketRecvTimeout — read data from socket with a timeout in seconds

Synopsis

T_INT4 TutSocketRecvTimeout(socket_fd, buf, size, flags, timeout, 
                            timeout_reached_return) 
T_INT4 socket_fd; 
T_PTR buf; 
T_INT4 size; 
T_INT4 flags; 
T_REAL8 timeout; 
T_BOOL *timeout_reached_return; 

Arguments

socket_fd — socket file descriptor to read from

buf — buffer to put data into

size — number of bytes to read

flags — flags for recv

timeout — maximum number of seconds to wait for size bytes of data to arrive

timeout_reached_return — storage for whether or not timeout was reached

Return Values

Number of bytes read if successful, -1 otherwise.

Diagnostics

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

Description

TutSocketRecvTimeout is a convenience function that reads data from a socket, subject to a timeout period. TutSocketRecvTimeout is useful when a program needs to have an upper limit on how long it waits for data to arrive on a socket. RTserver, for example, cannot block forever waiting for a new client to send connection information. TutSocketRecvTimeout keeps reading from the socket until the specified number of bytes have been received, or timeout has been reached.

If TutSocketRecvTimeout returns 0, then either timeout has been reached, or the socket peer has closed. The value TutSocketRecvTimeout stores in timeout_reached_return can be used to distinguish between these two cases.

The flags argument can be any flags accepted by the recv function. Refer to your operating system manuals for full information on these flags. Specify 0 for flags to use the default behavior.

Caution

TutSocketRecvTimeout is implemented with recv and select. If TutSocketRecvTimeout has to read multiple times from the socket, it reuses timeout each time it reads from the socket. For example, if TutSocketRecvTimeout has to read 5 times from the socket, up to 5 times timeout seconds could pass before TutSocketRecvTimeout would think timeout had been reached.

See Also

TutSocketRecvAll

Examples

This example distinguishes between EOF and the timeout period being reached:

bytes_read = TutSocketRecvTimeout(socket, buf, size, 0,  
                                  5.0,  &timeout_reached); 
TutOut("bytes read = %d, timeout_reached = %d\n", 
       bytes_read, timeout_reached); 
if (bytes_read == 0) { 
  if (timeout_reached) { 
    TutOut("Did not read any data in time.\n"); 
  }  
  else { 
    TutOut("The socket peer closed (EOF).\n"); 
  }  
}