.\" 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 für 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)
Während \fBselect\fR den Parameter \fItimeout\fR mitunter verändert, um
anzuzeigen, wie viel Zeit des Limits noch verblieben ist, lässt \fBpselect\fR
den Wert immer unverändert.
.TP
(iii)
Die \fBselect\fR-Funktion besitzt keinen \fIsigmask\fR-Parameter und
verhält sich wie \fBpselect\fR, das mit einer \fIsigmask\fR von NULL
aufgerufen wurde.
.PP
Es werden drei voneinander unabhängige 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 zurückkehren würde.  Diese Bedingung ist
insbesondere auch dann erfüllt, wenn der Deskriptor auf das Dateiende
verweist.)  Bei den in
.I writefds
angegebenen Deskriptoren wird reagiert, wenn weitere Zeichen geschrieben
werden können, und bei den in
.I exceptfds
angegebenen Deskriptoren, wenn etwas außergewöhnliches
passiert ist.  Kehrt der Systemaufruf zurück, sind die übergebenen
Mengen so verändert, dass sie anzeigen, welcher Deskriptor seinen
Status geändert hat.
.PP
Vier Makros stehen bereit, um mit diesen Mengen zu arbeiten.
.B FD_ZERO
löscht eine Menge,
.B FD_SET
und
.B FD_CLR
fügen einen Deskriptor zur Menge hinzu bzw. löschen diesen,
.B FD_ISSET
prüft, 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 höchsten 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 zurückkehren.  Ist das Zeitlimit null,
so kehren die Funktionen sofort zurück.  Besitzt
\fItimeout\fR selbst den Wert NULL, so wird kein Limit gesetzt, und
die Funktionen können 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, führt dann den
\fBselect\fR-Aufruf aus und stellt anschließend die ursprüngliche Maske
wieder her.
.PP
Die Idee hinter \fBpselect\fR geht zurück auf folgende Situation: Ein
Programm wartet gleichzeitig auf ein Signal oder eine
Veränderung an einem Datei-Deskriptor.  Trifft das Signal ein, so setzt der
Signalhandler eine globale Variable.  Im Hauptprogramm wird zunächst 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 führen, dass das Programm nicht mehr beendet wird.
\fBpselect\fR hingegen erlaubt es, diese so genannte Race Condition zu
umgehen, indem das Signal zunächst 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 "RÜCKGABEWERTE"
Bei Erfolg geben \fBselect\fR und \fBpselect\fR
die Anzahl der Deskriptoren zurück, deren Status sich geändert hat.
Der Rückgabewert kann auch null sein, wenn das Zeitlimit erreicht wurde,
bevor etwas interessantes passiert ist.
Wenn ein Fehler aufgetreten ist, wird \-1 zurückgegeben und 
.I errno
entsprechend gesetzt.  Die Mengen und
.I timeout
befinden sich dann in einem undefinierten Zustand.  Auf 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 ungültiger 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 für 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 Möglichkeit zu haben, ein
.B sleep
mit der Präzision von Bruchteilen einer Sekunde zu benutzen.
.PP
Bei Linux wird \fItimeout\fR derart verändert, 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 für 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
zurück und signalisiert, dass etwas von der Pipe gelesen werden kann.  Ein
anschließender \fBread\fR-Aufruf liefert jedoch null zurück, 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 fünf 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) müsste jetzt true sein. */
    else
        printf("Keine Dateien innerhalb von fünf Sekunden.\\n");

    exit(0);
}
.SH "KONFORM ZU"
4.4BSD.  (Die \fBselect\fR-Funktion trat das erste Mal in 4.2BSD auf.)
Gewöhnlich auch portierbar auf Nicht-BSD-Systeme (System V-Varianten
eingeschlossen), die eine Schnittstelle vom Typ des BSD-Socketlayers
unterstützen.  Zu beachten ist jedoch, dass die System V-Varianten
typischerweise die timeout-Variable vor der Rückkehr 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).