@CHIP-RTOS C Library - TCP/IP API

select

Await specified events on a selected set of sockets.

int select ( int nfds,
             fd_set far *readfds,
             fd_set far *writefds,
             fd_set far *exceptfds,
             const struct timeval FAR *timeout ) ;

Parameters

nfds

One greater than highest socket descriptor to be monitored in the following set of three fd_set objects.

readfds

Input/Output Parameter:   Pointer to a fd_set bit field that on input specifies the set of sockets to be monitored for receiver activity.   On return those sockets for which receiver data is ready among those specified for monitoring will have their bits in this field set to '1'.   All other bits will be zeroed.

writefds

Input/Output Parameter:   Pointer to a fd_set bit field that on input specifies the set of sockets to be monitored for send ready condition.   On return those sockets ready for send among those specified for monitoring here will have their bits in this field set to '1'.   All other bits will be zeroed.

exceptfds

Input/Output Parameter:   Pointer to a fd_set bit field that on input specifies the set of sockets to be monitored for error conditions.   On return those sockets with errors among those specified for monitoring here will have their bits in this field set to '1'.   All other bits will be zeroed.

timeout

Input Parameter:  Pointer to a timeval data structure which specifies the maximum wait time.   This pointer can be NULL to block until an event occurs on one of the specified sockets.

Return Value

0 if timeout, otherwise number of hits.   This is the number of selected sockets for which a specified event has occurred.

If nfds input parameter was invalid, then the return value will also be zero.

Comments

This function and its select_ms() variant API operate similarly to the standard Berkeley sockets implementation.   This API is useful when a single program thread is to manage the activity on more than one socket.   The thread can sleep for up to a specified amount of time, awaiting events on a selected set of sockets.   These events, selected by the caller, can be receiver activity, transmitter activity and/or socket error conditions.

The most common use of this API is to sleep on a combination of receiver activity or error conditions.   In this manner, your thread will wakeup when either data is received by one of your specified sockets, or if one of the sockets is closed by the peer.   For this usage, the writefds parameter would be NULL to indicate that you are not interested in hearing about any socket transmit activity.

Note that when only a single socket is involved, the recv() and recvfrom() API provide a more efficient receiver sleep mechanism than select().

This API's three pointer parameters to fd_set objects can point to the same object.   For example, for the receiver activity wait call, the readfds and exceptfds parameters could both reference the same fd_set object.   This is commonly done this way.   You lose the resolution over whether the error or receiver activity event occurred, but this can be resolved on a subsequent recv() (or recvfrom()) call that would normally follow a return from the select().

In the parameter description above for readfds , writefds and exceptfds it says "All other bits will be zeroed" .   Here "all bits" means those bits with indexes lower than the nfds input parameter value.   (Caller is responsible for zeroing the others with indexes higher).    This assumes that either no two pointers are pointing to the same fd_set or that the other events have not occurred.   The point here is that zeros are returned for sockets which have no event.   For the case where a pointer to the same fd_set object is passed for both the readfds and exceptfds parameters, for example, the returned bits will be set if either receiver data is ready or an error condition has occurred.   The bits set represent a logical OR of input parameter conditions which referenced the fd_set.

The nfds can be jammed to the MAX_BECK_SOCKETS constant value and this API will operate.  (The lazy programmer's approach.)   However, efficiency down inside the TCP/IP stack is improved if you confine the bit field range over which the system must operate by setting the nfds input parameter to one count greater than your highest socket descriptor bit set in any of your fd_set fields.

This API is reentrant so long as it is called for a mutually exclusive set of sockets.   However, when two threads call concurrently with an overlapping set of sockets specified, the last thread to call will receive a zero hit count return value.   This should be avoided.

The alternative non-standard calling convention offered by select_ms() is recommended when Berkeley sockets compatibility is not required.   This other API works the same except for that it uses the simplified timeout argument specified in milliseconds.

See Also

select_ms        recvfrom        recvfromto
recv        FD_Next        

RTOS API

This library function invokes a RTOS software interrupt. Refer to this RTOS API function's documentation for more details.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.22	V1.22	V1.22	V1.11	V1.00

Supported by @CHIP-RTOS C Library since version

CLIB
V2.08