.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" This manpage is copyright (C) 1992 Drew Eckhardt,
.\"                 copyright (C) 1995 Michael Shields.
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
.\" Modified 1995-05-18 by Jim Van Zandt <jrv@vanzandt.mv.com>
.\"
.\" Sun Feb 11 14:07:00 MET 1996  Martin Schulze  <joey@linux.de>
.\"	* translated from english to german
.\" Mon Dec  3 16:47:05 CET 2001  Daniel Kobras <kobras@linux.de>
.\"	* Typo fix.
.\"	* Document glibc2.1 addition pselect().
.\"
.TH SELECT 2 "3. Dezember 2001" "Linux" "Systemaufrufe"
.SH BEZEICHNUNG
select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \- Synchrone I/O-Multiplexsteuerung
.SH BERSICHT
.B #include <sys/time.h>
.br
.B #include <sys/types.h>
.br
.B #include <unistd.h>
.sp
\fBint select(int \fIn\fB, fd_set *\fIreadfds\fB,
fd_set *\fIwritefds\fB, fd_set *\fIexceptfds\fB,
struct timeval *\fItimeout\fB);
.sp
\fBint pselect(int \fIn\fB, fd_set *\fIreadfds\fB,
fd_set *\fIwritefds\fB, fd_set *\fIexceptfds\fB,
const struct timespec *\fItimeout\fB, sigset_t *\fIsigmask\fB);
.sp
.BI "FD_CLR(int " fd ", fd_set *" set );
.br
.BI "FD_ISSET(int " fd ", fd_set *" set );
.br
.BI "FD_SET(int " fd ", fd_set *" set );
.br
.BI "FD_ZERO(fd_set *" set );
.fi
.SH BESCHREIBUNG
Die Funktionen \fBselect\fR und \fBpselect\fR
berwachen den Dateistatus fr eine Reihe von Datei-Deskriptoren.
.PP
Die Funktionsweise der beiden Varianten ist identisch, abgesehen von
drei Unterschieden:
.TP
(i)
The \fBselect\fR-Funktion verwendet zur Angabe von Zeitlimits eine Struktur
vom Typ \fIstruct timeval\fR (mit Sekunden und Mikrosekunden), \fBpselect\fR
hingegen den Typ \fIstruct timespec\fR (mit Sekunden und Nanosekunden).
Die Strukturen sind ber /usr/include/sys/time.h definiert als:
.sp
.nf
struct timeval { 
.in +8
long    tv_sec;         /* Sekunden */
long    tv_usec;        /* Mikrosekunden */
.in -8
};

und

.nf
struct timespec {
.in +8
long    tv_sec;         /* Sekunden */
long    tv_nsec;        /* Nanosekunden */
.in -8
};
.fi
.TP
(ii)
Whrend \fBselect\fR den Parameter \fItimeout\fR mitunter verndert, um
anzuzeigen, wieviel Zeit des Limits noch verblieben ist, lsst \fBpselect\fR
den Wert immer unverndert.
.TP
(iii)
Die \fBselect\fR-Funktion besitzt keinen \fIsigmask\fR-Parameter und
verhlt sich wie \fBpselect\fR, das mit einer \fIsigmask\fR von NULL
aufgerufen wurde.
.PP
Es werden drei voneinander unabhngige Mengen von Deskriptoren
behandelt.  Bei den in
.I readfds
enthaltenen wird darauf geachtet, ob neue Zeichen zum Lesen
ankommen.  (Genauer, es wird kontrolliert, ob ein nachfolgender
\fBread\fR-Systemaufruf sofort zurckkehren wrde.  Diese Bedingung ist
insbesondere auch dann erfllt, wenn der Deskriptor auf das Dateiende
verweist.)  Bei den in
.I writefds
angegebenen Deskriptoren wird reagiert, wenn weitere Zeichen geschrieben
werden knnen, und bei den in
.I exceptfds
angegebenen Deskriptoren, wenn etwas auergewhnliches
passiert ist.  Kehrt der Systemaufruf zurck, sind die bergebenen
Mengen so verndert, dass sie anzeigen, welcher Deskriptor seinen
Status gendert hat.
.PP
Vier Makros stehen bereit, um mit diesen Mengen zu arbeiten.
.B FD_ZERO
lscht eine Menge,
.B FD_SET
und
.B FD_CLR
fgen einen Deskriptor zur Menge hinzu bzw. lschen diesen,
.B FD_ISSET
prft, ob der Deskriptor in der Menge enthalten ist.  Das ist
insbesondere nach einem \fBselect\fR- oder \fBpselect\fR-Aufruf
sinnvoll.
.PP
.I n
entspricht der Zahl des am hchsten nummerierten Datei-Deskriptors in allen
drei Mengen, plus 1.
.PP
.I timeout
gibt ein Zeitlimit an, das \fBselect\fR und \fBpselect\fR
maximal verstreichen lassen, bevor sie zurckkehren.  Ist das Zeitlimit null,
so kehren die Funktionen sofort zurck.  Besitzt
\fItimeout\fR selbst den Wert NULL, so wird kein Limit gesetzt, und
die Funktionen knnen unendlich lange blockieren.
.PP
.I sigmask
ist entweder NULL oder ein Zeiger auf eine Signalmaske wie in
\fBsigprocmask\fR(2) beschrieben.  Im zweiten Fall ersetzt \fBpselect\fR
die aktuelle Signalmaske durch \fIsigmask\fR, fhrt dann den
\fBselect\fR-Aufruf aus und stellt anschlieend die ursprngliche Maske
wieder her.
.PP
Die Idee hinter \fBpselect\fR geht zurck auf folgende Situation: Ein
Programm wartet gleichzeitig auf ein Signal oder eine
Vernderung an einem Datei-Deskriptor.  Trifft das Signal ein, so setzt der
Signalhandler eine globale Variable.  Im Hauptprogramm wird zunchst getestet,
ob die Variable gesetzt ist und andernfalls ein \fBselect\fR-Aufruf
gestartet.  Trifft das Signal zwischen dem Test und dem \fBselect\fR-Aufruf
ein, so kann das dazu fhren, dass das Programm nicht mehr beendet wird.
\fBpselect\fR hingegen erlaubt es, diese sogenannte Race Condition zu
umgehen, indem das Signal zunchst geblockt, getestet und erst unmittelbar
mit dem \fBselect\fR-Aufruf wieder freigegeben wird.  Da der Linux-Kernel
bislang keinen speziellen \fBpselect\fR-Systemaufruf bereit stellt, muss
die aktuelle glibc2 ihn durch mehrere Aufrufe emulieren.  Die Fehlerquelle
ist daher auch mit \fBpselect\fR nach wie vor vorhanden.
.PP
.SH "RCKGABEWERTE"
Bei Erfolg geben \fBselect\fR und \fBpselect\fR
die Anzahl der Deskriptoren zurck, deren Status sich gendert hat.
Der Rckgabewert kann auch null sein, wenn das Zeitlimit erreicht wurde,
bevor etwas interessantes passiert ist.
Wenn ein Fehler aufgetreten ist, wird \-1 zurckgegeben und 
.I errno
entsprechend gesetzt.  Die Mengen und
.I timeout
befinden sich dann in einem undefinierten Zustand.  uf ihren Inhalt sollte
man sich folglich bei einem Fehler nicht mehr verlassen.
.PP
.SH FEHLER
.TP 0.8i
.B EBADF
In einer der Mengen wurde ein ungltiger Datei-Deskriptor angegeben.
.TP
.B EINTR 
Ein nicht-blockiertes Signal wurde empfangen.
.TP
.B EINVAL 
.I n
ist negativ.
.TP
.B ENOMEM
.B select
war nicht in der Lage, Speicher fr die internen Tabellen zu bekommen.
.PP
.SH ANMERKUNGEN
Einige Programme rufen
.B select
mit drei leeren Mengen,
.I n
gleich null und einem von null verschiedenen
.I timeout
auf, um eine portable Mglichkeit zu haben, ein
.B sleep
mit der Przision von Bruchteilen einer Sekunde zu benutzen.
.PP
Bei Linux wird \fItimeout\fR derart verndert, dass es dem noch nicht
verstrichenen Teil des Zeitlimits entspricht.  Die meisten Implementierungen
anderer Betriebssysteme unterlassen dies.  Das bringt Probleme mit sich, wenn
unter Linux geschriebener Quellcode, der \fItimeout\fR auswertet, auf andere
Betriebssysteme portiert wird, und wenn Quellcode von anderen Betriebssystemen
auf Linux portiert wird, der das struct timeval fr mehrere \fBselect\fRs in
einer Schleife verwendet, ohne ihn jedesmal neu zu initialisieren.  Portabler
Code sollte daher annehmen, dass \fItimeout\fR undefiniert ist, nachdem
\fBselect\fR beendet wurde.
.PP
Wenn der einzige Schreiber eine Named-Pipe geschlossen hat, kehrt \fBselect\fR
zurck und signalisiert, dass etwas von der Pipe gelesen werden kann.  Ein
anschlieender \fBread\fR-Aufruf liefert jedoch null zurck, da das Dateiende
erreicht ist.  Code, der annimmt, dass \fBselect\fR in diesem Fall blockiert,
sollte die Pipe mit \fBO_RDWR\fR statt \fBO_RDONLY\fR ffnen.
.PP
.SH BEISPIEL
.nf
#include <stdio.h>
#include <sys/time.h>
#include <sys/types.h>
#include <unistd.h>

int main(void)
{
    fd_set rfds;
    struct timeval tv;
    int retval;

    /* Achte auf stdin (fd 0), um zu sehen, wenn es
     * Eingaben gibt.
     */
    FD_ZERO(&rfds);
    FD_SET(0, &rfds);
    /* Warte bis zu fnf Sekunden. */
    tv.tv_sec = 5;
    tv.tv_usec = 0;

    retval = select(1, &rfds, NULL, NULL, &tv);
    /* Verla Dich jetzt blo nicht auf den Wert von tv! */

    if (retval)
        printf("Daten sind jetzt da.\\n");
        /* FD_ISSET(0, &rfds) mte jetzt true sein. */
    else
        printf("Keine Datein innerhalb von fnf Sekunden.\\n");

    exit(0);
}
.SH "KONFORM ZU"
4.4BSD.  (Die \fBselect\fR-Funktion trat das erste Mal in 4.2BSD auf.)
Gewhnlich auch portierbar auf Nicht-BSD-Systeme (System V-Varianten
eingeschlossen), die eine Schnittstelle vom Typ des BSD-Socketlayers
untersttzen.  Zu beachten ist jedoch, dass die System V-Varianten
typischerweise die timeout-Variable vor der Rckkehr setzen.  Bei den
BSD-Varianten ist das nicht blich.
.PP
Die \fBpselect\fR-Funktion ist in IEEE Std 1003.1g-2000 (POSIX.1g) definiert.
Sie ist seit glibc2.1 implementiert.  Auch glibc2.0 besitzt eine Funktion
dieses Namens, die jedoch keinen Parameter \fIsigmask\fR verwendet.
.fi
.SH "SIEHE AUCH"
.BR accept (2),
.BR connect (2),
.BR poll (2),
.BR read (2),
.BR recv (2),
.BR send (2),
.BR sigprocmask (2),
.BR write (2).