fseek.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: cc735f9ff7aaa32e5ed2eae501f9942c0d05493c Maintainer: dallas Status: ready -->
<!-- CREDITS: mowangjuanzi -->
<refentry xml:id="function.fseek" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>fseek</refname>
  <refpurpose>在文件指针中定位</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>int</type><methodname>fseek</methodname>
   <methodparam><type>resource</type><parameter>stream</parameter></methodparam>
   <methodparam><type>int</type><parameter>offset</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>whence</parameter><initializer><constant>SEEK_SET</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   在与 <parameter>stream</parameter> 关联的文件中设定文件指针位置。新位置从文件头开始以字节数度量，是以
   <parameter>whence</parameter> 指定的位置加上 <parameter>offset</parameter>。
  </para>
  <para>
   一般来说，允许定位超过文件末尾的位置；如果随后写入数据，则从文件末尾和定位位置之间已读取的任何未写入区域将产生值为 0
   的字节。但是，某些 stream 可能不支持此行为，尤其是当它们具有底层固定大小的存储时。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>stream</parameter></term>
     <listitem>
      &fs.file.pointer;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>offset</parameter></term>
     <listitem>
      <para>
       偏移量。
      </para>
      <para>
       要移动到文件尾之前的位置，必须传递负数值给 <parameter>offset</parameter>，而且
       <parameter>whence</parameter> 参数设置为 <constant>SEEK_END</constant>。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>whence</parameter></term>
     <listitem>
      <para>
       <parameter>whence</parameter> 值是：
       <simplelist>
        <member><constant>SEEK_SET</constant> - 设定位置等于距文件开头为 <parameter>offset</parameter> 字节。</member>
        <member><constant>SEEK_CUR</constant> - 设定位置为当前位置加上 <parameter>offset</parameter> 字节。</member>
        <member><constant>SEEK_END</constant> - 设定位置为文件尾加上 <parameter>offset</parameter> 字节。</member>
       </simplelist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
    成功返回 <literal>0</literal>；否则返回 <literal>-1</literal>。
  </para>
  <warning>
   <simpara>
    此函数是为了模仿 C 语言中同名函数而创建的。请注意返回值，因为它们与 PHP 中的期望值不同。
   </simpara>
  </warning>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>fseek</function> 示例</title>
    <programlisting role="php">
<![CDATA[
<?php

$fp = fopen('somefile.txt', 'r');

// read some data
$data = fgets($fp, 4096);

// move back to the beginning of the file
// same as rewind($fp);
fseek($fp, 0);

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    如果使用附加模试（<literal>a</literal> 或
    <literal>a+</literal>），任何写入文件数据都会被附加上去，而文件的位置将会被忽略，调用
    <function>fseek</function> 的结果尚未定义。
   </para>
  </note>
  <note>
   <para>
    并非所有 stream 都支持定位。对于不支持定位的 stream，从当前位置向前定位是通过读取和丢弃数据来实现的；其他形式的定位将会失败。
   </para>
  </note>
 </refsect1>
 
  <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>ftell</function></member>
    <member><function>rewind</function></member>
   </simplelist>
  </para>
 </refsect1>
 
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->