<?xml version="1.0" encoding="utf-8"?>

<refentry xml:id="function.socket-select" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>socket_select</refname>

<refpurpose>Exécute l'appel système select() sur un tableau de sockets avec une durée d'expiration</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>int</type><type>false</type></type><methodname>socket_select</methodname>

<methodparam><type class="union"><type>array</type><type>null</type></type><parameter role="reference">read</parameter></methodparam>

<methodparam><type class="union"><type>array</type><type>null</type></type><parameter role="reference">write</parameter></methodparam>

<methodparam><type class="union"><type>array</type><type>null</type></type><parameter role="reference">except</parameter></methodparam>

<methodparam><type class="union"><type>int</type><type>null</type></type><parameter>seconds</parameter></methodparam>

<methodparam choice="opt"><type>int</type><parameter>microseconds</parameter><initializer>0</initializer></methodparam>

</methodsynopsis>

<para>

<function>socket_select</function> accepte un tableau de sockets et

attend qu'elles changent de statut. Ceux qui sont familiers avec les

sockets de BSD reconnaîtront dans ces tableaux de sockets les

jeux de pointeurs de fichiers. Trois tableaux indépendants

de sockets sont surveillés.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>read</parameter></term>

<listitem>

<para>

Les sockets listés dans le paramètre <parameter>read</parameter>

seront surveillés en lecture : pour savoir quand ils sont

disponibles en lecture (plus précisément, si une lecture

ne va pas bloquer, en particulier, un socket a déjà

atteint une fin de fichier, auquel cas <function>socket_read</function>

retournera une chaîne de taille zéro).

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>write</parameter></term>

<listitem>

<para>

Les sockets listés dans <parameter>write</parameter> seront surveillés

en écriture : pour voir si une écriture ne va pas bloquer.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>except</parameter></term>

<listitem>

<para>

Les sockets listés dans <parameter>except</parameter> seront surveillés pour

leurs exceptions.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>seconds</parameter></term>

<listitem>

<para>

Les paramètres <parameter>seconds</parameter> et <parameter>microseconds</parameter>

ensembles forment le paramètre <literal>timeout</literal> (délai d'expiration).

Le <literal>timeout</literal> est la durée maximale de temps avant que

<function>socket_select</function> ne se termine.

<parameter>seconds</parameter> peut être zéro, ce qui fera que

<function>socket_select</function> retournera immédiatement. C'est très

pratique pour faire du polling (sondage). Si <parameter>seconds</parameter> est &null;

(pas de timeout), <function>socket_select</function> peut se bloquer indéfiniment.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>microseconds</parameter></term>

<listitem>

<para>

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

<warning>

<para>

En sortie de fonction, les tableaux sont modifiés pour indiquer

quels sockets ont changé d'état.

</para>

</warning>

<para>

Il n'est pas nécessaire de passer tous les tableaux à

<function>socket_select</function>. Il est possible des omettre, ou

utiliser un tableau vide, ou encore &null; à la place. Il ne faut pas oublier

que ces tableaux sont passés par <emphasis>référence</emphasis> et

seront modifiés par <function>socket_select</function>.

</para>

<note>

<para>

À cause d'une limitation du moteur Zend actuel, il n'est pas possible

de passer une constante comme &null; directement comme paramètre à cette

fonction, qui attend une valeur par référence. À la place, utiliser

un tableau temporaire ou une expression dont le membre de gauche

est une variable temporaire :

<example>

<title>Passer &null; à <function>socket_select</function></title>

<programlisting role="php">

</programlisting>

</example>

</para>

</note>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

En cas de succès, <function>socket_select</function> retourne le nombre de

sockets contenues dans les tableaux modifiés. Ce nombre peut être zéro si

la durée maximale d'attente a été atteinte. En cas d'erreur, &false;

est retourné. Le code d'erreur généré peut être obtenu en appelant la

fonction <function>socket_last_error</function>.

</para>

<note>

<para>

Il faut s'assurer bien d'utiliser l'opérateur <literal>===</literal>

lorsque l'on vérifie les erreurs. Étant donné que

<function>socket_select</function> peut retourner 0, la comparaison

avec &false; via <literal>==</literal> donnerait &true; :

<example>

<title>Analyser le résultat de <function>socket_select</function></title>

<programlisting role="php">

</programlisting>

</example>

</para>

</note>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Exemple avec <function>socket_select</function></title>

<programlisting role="php">

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<para>

Il faut se méfier des implémentations de sockets, qui doivent être manipulées avec

délicatesse. Quelques règles de base :

<itemizedlist>

<listitem>

<simpara>

Il faut toujours essayer d'utiliser <function>socket_select</function>

sans timeout. Le programme ne devrait avoir rien à faire si

il n'y a pas de données disponibles. Le code qui dépend d'un

timeout est généralement peu portable, et difficile à déboguer.

</simpara>

</listitem>

<listitem>

<simpara>

Un socket ne doit pas être ajouté à l'un des tableaux en paramètre,

si on ne souhaite pas vérifier le résultat après l'appel à

<function>socket_select</function>. Après le retour de

<function>socket_select</function>, tous les sockets dans tous les

tableaux doivent être vérifiés. Tout socket qui est disponible en

écriture ou en lecture doit être utilisé pour écrire ou lire.

</simpara>

</listitem>

<listitem>

<simpara>

Si l'on écrit ou lit avec un socket retourné dans un tableau,

il faut savoir qu'il ne pourra pas écrire ou lire toutes les données

que l'on demande. Il faut être prêt à ne pouvoir lire qu'un seul octet.

</simpara>

</listitem>

<listitem>

<simpara>

Il est commun à la plupart des implémentations de socket que la seule

exception interceptée par les sockets dans le tableau

<parameter>except</parameter> soit le cas des données hors limites,

reçues par un socket.

</simpara>

</listitem>

</itemizedlist>

</para>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>socket_read</function></member>

<member><function>socket_write</function></member>

<member><function>socket_last_error</function></member>

<member><function>socket_strerror</function></member>

</simplelist>

</para>

</refsect1>

</refentry>