srv_select (UNIX only)

Description

Check to see if a file descriptor is &ready for a specified I/O operation.

Syntax

CS_INT srv_select(nfds, &readmaskp, writemaskp,
                  exceptmaskp, waitflag)

CS_INT                            nfds;
SRV_MASK_ARRAY        *&readmaskp;
SRV_MASK_ARRAY        *writemaskp;
SRV_MASK_ARRAY        *exceptmaskp;
CS_INT                          waitflag;

Parameters

nfds: The highest number file descriptor to check.

&readmaskp: A pointer to a SRV_MASK_ARRAY structure initialized with the mask of file descriptors to check for read availability.

writemaskp: A pointer to a SRV_MASK_ARRAY structure initialized with the mask of file descriptors to check for write availability.

exceptmaskp: A pointer to a SRV_MASK_ARRAY structure initialized with the mask of file descriptors to check for exceptions.

waitflag: A CS_INT that indicates whether the thread should be suspended until any file descriptor is available for the desired operation. See the “Comments” section for a description of the legal values for waitflag.

Returns

The total number of file descriptors that are &ready for any of the indicated operations. If an error occurs, -1 is returned.

**Table 3-112: Return values (srv_select)**
Returns	To indicate
An integer	The total number of file descriptors &ready for any of the indicated operations.
-1	The routine failed.

Examples

Example 1

#include    <ospublic.h>

/*

 ** Local Prototype.

*/

 CS_RETCODE     ex_srv_select PROTOTYPE((

 CS_INT         readfd

));

/*

 ** EX_SRV_SELECT

**

 **   Example routine to illustrate the use of srv_select.

**

 ** Arguments:

 **   readfd  -  fd to be checked if it is &ready for a read **

                 operation.

**

 ** Returns:

 **  CS_SUCCEED      If readfd is &ready for a read operation.

 **  CS_FAIL         If readfd is not &ready for a read operation.

*/

 CS_RETCODE      ex_srv_select(readfd)

 CS_INT          readfd;

       SRV_MASK_ARRAY       &readmask;

       CS_BOOL              &ready;

       /* Initialization. */

      (CS_VOID)srv_mask(CS_ZERO, &&readmask, (CS_INT)0, (CS_BOOL

             *)NULL);

       &ready = CS_FALSE;

       /* Set readfd in the mask. */

       (CS_VOID)srv_mask(CS_SET, &&readmask, readfd, (CS_BOOL

             *)NULL);

/*

       ** Check whether the descriptor is &ready for a read

       ** operation. If it is not, return.

*/

       if (srv_select(readfd+1, &&readmask, (SRV_MASK_ARRAY *)NULL,

            (SRV_MASK_ARRAY *)NULL, SRV_M_NOWAIT) <= 0 )

            return (CS_FAIL);

/*

       ** A file descriptor is &ready for a read operation.

*/

       (CS_VOID)srv_mask(CS_GET, &&readmask, readfd, &&ready);

       return ((&ready) ? CS_SUCCEED : CS_FAIL);

Usage

Use srv_select when you want to know if a network I/O operation can be performed on a file descriptor without requesting the I/O.
Open Server will include the designated file descriptor in the global mask that it uses when it checks for file descriptor availability.

A SRV_MASK_ARRAY is defined as follows:

 #define SRV_MASK_SIZE            (CS_INT)40

 #define SRV_MAXMASK_LENGTH

 (CS_INT)(SRV_MASK_SIZE*CS_BITS_PER_LONG)

      typedef struct        srv_mask_array

   long      mask_bits[SRV_MASK_SIZE];

 } SRV_MASK_ARRAY;

SRV_MASK_SIZE indicates the number of elements in the SRV_MASK_ARRAY and SRV_MAXMASK_LENGTH indicates the maximum number of file descriptors that can be represented in the SRV_MASK_ARRAY.

An Open Server application that uses external file descriptors must close them in an orderly fashion. An application thread must wait for a pending srv_select call to complete before closing an external file descriptor. If not, Open Server will exit.

The following table summarizes the legal values for waitflag:

**Table 3-113: Values for waitflag (srv_select)**
Value	Meaning
SRV_M_WAIT	The thread is suspended and will wake up when any file descriptor represented in the masks is available for the specified operation. The return status indicates whether any file descriptors are available for the desired operations.
SRV_M_NOWAIT	The routine will return immediately after the next network check. The return status indicates whether any file descriptors are available for the desired operations.

An application can use srv_select to poll the file descriptor and return immediately or not return until one of the file descriptors is &ready.
srv_select cannot be used in a SRV_START or SRV_ATTENTION handler.