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

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

<refnamediv>

<refname>socket_write</refname>

<refpurpose>ソケットに書き込む</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

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

<methodparam><type>Socket</type><parameter>socket</parameter></methodparam>

<methodparam><type>string</type><parameter>data</parameter></methodparam>

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

</methodsynopsis>

<para>

関数 <function>socket_write</function> は、

<parameter>data</parameter> の内容をソケット

<parameter>socket</parameter> に書き込みます。

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>socket</parameter></term>

<listitem>

<para>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>data</parameter></term>

<listitem>

<para>

書き込まれるバッファ。

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>length</parameter></term>

<listitem>

<para>

オプションのパラメータ <parameter>length</parameter> で、

ソケットに書き込むバイト数を指定することが可能です。

この値が <parameter>data</parameter> より大きい場合、自動的に <parameter>data</parameter> のサイズに切り詰められます。

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

ソケットへの書き込みに成功したデータのバイト数を返します。&return.falseforfailure;。

エラーコードは <function>socket_last_error</function>

を用いて取得することができ、この値を <function>socket_strerror</function>

に渡すことでエラー情報を文字列で取得可能です。

</para>

<note>

<para>

<function>socket_write</function> がゼロを返すことも十分ありえます。

これは、書き込むデータが存在しなかったことを意味します。

エラーをチェックするために &false; かどうかを調べる際には、必ず

<literal>===</literal> 演算子を使用しましょう。

</para>

</note>

</refsect1>

<refsect1 role="changelog">

&reftitle.changelog;

<informaltable>

<tgroup cols="2">

<thead>

<row>

<entry>&Version;</entry>

<entry>&Description;</entry>

</row>

</thead>

<tbody>

&sockets.changelog.socket-param;

<row>

<entry>8.0.0</entry>

<entry>

<parameter>length</parameter> は、nullable になりました。

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</refsect1>

<refsect1 role="notes">

&reftitle.notes;

<note>

<para>

<function>socket_write</function> は、<parameter>data</parameter> の内容を必ずしもすべて

書き込むとは限りません。ネットワークバッファの状態にもよりますが、

ある量のデータだけ、たとえば 1 バイトだけ書き込まれたのであったとしても、

そして <parameter>data</parameter> のサイズがそれより大きかったとしても、

それはエラーではなく正常な動作です。

そのため、<parameter>data</parameter> の残りが転送されたことを保証するには、

ループを使う必要があります。

</para>

</note>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><function>socket_accept</function></member>

<member><function>socket_bind</function></member>

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

<member><function>socket_listen</function></member>

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

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

</simplelist>

</para>

</refsect1>

</refentry>