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

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

<refnamediv>

<refname>fsockopen</refname>

<refpurpose>Abre un socket de conexión Internet o Unix</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>resource</type><type>false</type></type><methodname>fsockopen</methodname>

<methodparam><type>string</type><parameter>hostname</parameter></methodparam>

<methodparam choice="opt"><type>int</type><parameter>port</parameter><initializer>-1</initializer></methodparam>

<methodparam choice="opt"><type>int</type><parameter role="reference">error_code</parameter><initializer>&null;</initializer></methodparam>

<methodparam choice="opt"><type>string</type><parameter role="reference">error_message</parameter><initializer>&null;</initializer></methodparam>

<methodparam choice="opt"><type class="union"><type>float</type><type>null</type></type><parameter>timeout</parameter><initializer>&null;</initializer></methodparam>

</methodsynopsis>

<para>

Inicializa una conexión por socket al recurso especificado por

<parameter>hostname</parameter>.

</para>

<para>

PHP soporta los objetivos en los dominios Internet y Unix como se describe en

<xref linkend="transports"/>. Una lista de los tipos de transportes también puede

ser encontrada utilizando la función <function>stream_get_transports</function>.

</para>

<para>

El socket se abrirá por omisión en modo bloqueante. Se puede

cambiar de modo utilizando: <function>stream_set_blocking</function>.

</para>

<para>

La función <function>stream_socket_client</function> es similar

pero proporciona más opciones, incluyendo la conexión no bloqueante

y la posibilidad de proporcionar un contexto de flujo.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>hostname</parameter></term>

<listitem>

<para>

Si el soporte OpenSSL <link linkend="openssl.installation">está

instalado</link>, se puede prefijar <parameter>hostname</parameter>

con <literal>ssl://</literal> o <literal>tls://</literal> para utilizar

una conexión cliente SSL o TLS sobre TCP/IP para conectarse al host

remoto.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>port</parameter></term>

<listitem>

<para>

El número del puerto. Este argumento puede ser omitido e ignorado

utilizando el valor <literal>-1</literal> para los transportes

que no utilizan puertos, como <literal>unix://</literal>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>error_code</parameter></term>

<listitem>

<para>

Si se proporciona, contiene el número del error del sistema que ocurre

durante la llamada al sistema <literal>connect()</literal>.

</para>

<para>

Si el valor devuelto por <parameter>error_code</parameter> es

<literal>0</literal> y la función devuelve &false;, puede ser una indicación

de que el error ocurrió antes de la llamada a <literal>connect()</literal>. La mayoría de las veces,

esto se debe a un problema de inicialización del socket.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>error_message</parameter></term>

<listitem>

<para>

El mensaje de error, en forma de &string;.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>timeout</parameter></term>

<listitem>

<para>

El tiempo máximo de espera, en segundos. Si es &null; el parámetro &php.ini;

<link linkend="ini.default-socket-timeout">default_socket_timeout</link> es utilizado.

</para>

<note>

<para>

Si se necesita establecer un tiempo límite para leer/escribir datos a través de este socket, utilice la función

<function>stream_set_timeout</function>, ya que el argumento

<parameter>timeout</parameter> de la función

<function>fsockopen</function> se aplica únicamente durante la conexión del socket.

</para>

</note>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

<function>fsockopen</function> devuelve un puntero de fichero que puede

ser utilizado con otras funciones de ficheros, tales como

<function>fgets</function>, <function>fgetss</function>,

<function>fputs</function>, <function>fclose</function> y

<function>feof</function>. Si la llamada falla, la función devuelve

&false;.

</para>

</refsect1>

<refsect1 role="errors">

&reftitle.errors;

<para>

Lanza una alerta de tipo <constant>E_WARNING</constant> si el argumento

<parameter>hostname</parameter> no es un dominio válido.

</para>

</refsect1>

<refsect1 role="changelog"><!-- {{{ -->

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

<row>

<entry>8.0.0</entry>

<entry>

<parameter>timeout</parameter> es ahora nullable.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Ejemplo con <function>fsockopen</function></title>

<programlisting role="php">

</programlisting>

</example>

</para>

<para>

<example>

<title>Uso de una conexión UDP</title>

<para>

El ejemplo a continuación describe cómo leer la fecha y la hora gracias a

un servicio UDP "daytime" (puerto 13), en su propia máquina.

</para>

<programlisting role="php">

</programlisting>

</example>

</para>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<para>

Dependiendo de los entornos, el tipo 'dominio Unix' o la opción

<parameter>timeout</parameter> no siempre están disponibles.

</para>

</note>

<warning>

<para>

Los sockets UDP parecen haber sido abiertos sin error,

incluso si el host remoto no es accesible. El error aparece entonces

solo cuando se intenta leer/escribir en el socket.

La razón de esto es que UDP es un protocolo <literal>"connectionless"</literal>,

lo que significa que el sistema no intentará establecer un enlace para el socket

hasta que no deba recibir/enviar datos.

</para>

</warning>

&ipv6.brackets;

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>pfsockopen</function></member>

<member><function>stream_socket_client</function></member>

<member><function>stream_set_blocking</function></member>

<member><function>stream_set_timeout</function></member>

<member><function>fgets</function></member>

<member><function>fgetss</function></member>

<member><function>fwrite</function></member>

<member><function>fclose</function></member>

<member><function>feof</function></member>

<member><function>socket_connect</function></member>

<member>La <link linkend="ref.curl">extensión Curl</link></member>

</simplelist>

</para>

</refsect1>

</refentry>