[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 2

select Subroutine

Purpose

Checks the I/O status of multiple file descriptors and message queues.

Library

Standard C Library (libc.a)

Syntax

#include <sys/time.h>
#include <sys/select.h>
#include <sys/types.h>
int select (Nfdsmsgs, ReadList, WriteList, ExceptList, TimeOut)
int Nfdsmsgs;
struct sellist *ReadList, *WriteList, *ExceptList;
struct timeval *TimeOut;

Description

The select subroutine checks the specified file descriptors and message queues to see if they are ready for reading (receiving) or writing (sending), or if they have an exceptional condition pending.

When selecting on an unconnected stream socket, select returns when the connection is made. If selecting on a connected stream socket, then the ready message indicates that data can be sent or received. Files descriptors of regular files always select true for read, write, and exception conditions. For more information on sockets, refer to "Understanding Socket Connections" and the related "Checking for Pending Connections Example Program" dealing with pending connections in AIX Communications Programming Concepts.

Parameters

Nfdsmsgs Specifies the number of file descriptors and the number of message queues to check. The low-order 16 bits give the length of a bit mask that specifies which file descriptors to check; the high-order 16 bits give the size of an array that contains message queue identifiers. If either half of the Nfdsmsgs parameter is equal to a value of 0, the corresponding bit mask or array is assumed not to be present.
TimeOut Specifies either a null pointer or a pointer to a timeval structure that specifies the maximum length of time to wait for at least one of the selection criteria to be met. The timeval structure is defined in the /usr/include/sys/time.h file and it contains the following members: 
struct timeval {
   int tv_sec;        /* seconds       */
   int tv_usec;       /* microseconds  */
    };

The number of microseconds specified in TimeOut.tv_usec, a value from 0 to 999999, is set to one millisecond by Version 3 of the operating system if the process does not have root user authority and the value is less than one millisecond.

If the TimeOut parameter is a null pointer, the select subroutine waits indefinitely, until at least one of the selection criteria is met. If the TimeOut parameter points to a timeval structure that contains zeros, the file and message queue status is polled, and the select subroutine returns immediately.

ReadList, WriteList, ExceptList
                          Specify what to check for reading, writing, and exceptions, respectively. Together, they specify the selection criteria. Each of these parameters points to a sellist structure, which can specify both file descriptors and message queues. Your program must define the sellist structure in the following form: 
struct sellist
{
int fdsmask[F];        /* file descriptor bit mask  */
int msgids[M];         /* message queue identifiers */
};

The fdsmask array is treated as a bit string in which each bit corresponds to a file descriptor. File descriptor n is represented by the bit (1 << (n mod bits)) in the array element fdsmask[n / BITS(int)]. (The BITS macro is defined in the values.h file.) Each bit that is set to 1 indicates that the status of the corresponding file descriptor is to be checked.

Note: The low-order 16 bits of the Nfdsmsgs parameter specify the number of bits (not elements) in the fdsmask array that make up the file descriptor mask. If only part of the last int is included in the mask, the appropriate number of low-order bits are used, and the remaining high-order bits are ignored. If you set the low-order 16 bits of the Nfdsmsgs parameter to 0, you must not define an fdsmask array in the sellist structure.

Each int of the msgids array specifies a message queue identifier whose status is to be checked. Elements with a value of -1 are ignored. The high-order 16 bits of the Nfdsmsgs parameter specify the number of elements in the msgids array. If you set the high-order 16 bits of the Nfdsmsgs parameter to 0, you must not define a msgids array in the sellist structure.

Note: The arrays specified by the ReadList, WriteList, and ExceptList parameters are the same size because each of these parameters points to the same sellist structure type. However, you need not specify the same number of file descriptors or message queues in each. Set the file descriptor bits that are not of interest to 0, and set the extra elements of the msgids array to -1.

You can use the SELLIST macro defined in the sys/select.h file to define the sellist structure. The format of this macro is:

SELLIST(f, m) declarator . . . ;

where f specifies the size of the fdsmask array, m specifies the size of the msgids array, and each declarator is the name of a variable to be declared as having this type.

Return Values

Upon successful completion, the select subroutine returns a value that indicates the total number of file descriptors and message queues that satisfy the selection criteria. The fdsmask bit masks are modified so that bits set to 1 indicate file descriptors that meet the criteria. The msgids arrays are altered so that message queue identifiers that do not meet the criteria are replaced with a value of -1.

The return value is similar to the Nfdsmsgs parameter in that the low-order 16 bits give the number of file descriptors, and the high-order 16 bits give the number of message queue identifiers. These values indicate the sum total that meet each of the read, write, and exception criteria. Therefore, the same file descriptor or message queue can be counted up to three times. You can use the NFDS and NMSGS macros found in the sys/select.h file to separate out these two values from the return value. For example, if rc contains the value returned from the select subroutine, NFDS(rc) is the number of files selected, and NMSGS(rc) is the number of message queues selected.

If the time limit specified by the TimeOut parameter expires, the select subroutine returns a value of 0.

If a connection-based socket is specified in the Readlist parameter and the connection disconnects, the select subroutine returns successfully, but the recv subroutine on the socket will return a value of 0 to indicate the socket connection has been closed.

If the select subroutine is unsuccessful, it returns a value of -1 and sets the global variable errno to indicate the error. In this case, the contents of the structures pointed to by the ReadList, WriteList, and ExceptList parameters are unpredictable.

Error Codes

The select subroutine is unsuccessful if one of the following are true:

EBADF An invalid file descriptor or message queue identifier was specified.
EAGAIN Allocation of internal data structures was unsuccessful.
EINTR A signal was caught during the select subroutine and the signal handler was installed with an indication that subroutines are not to be restarted.
EINVAL One of the parameters to the select subroutine contained a value that is not valid.
EFAULT The ReadList, WriteList, ExceptList, or TimeOut parameter points to a location outside of the address space of the process.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

The select subroutine is also supported for compatibility with previous releases of this operating system and with BSD systems.

Related Information

The poll subroutine.

The Input and Output Handling Programmer's Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

[ Previous | Next | Contents | Glossary | Home | Search ]