mingw/html/lib/IO/Seekable.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>IO::Seekable - supply seek based methods for I/O objects</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;IO::Seekable - supply seek based methods for I/O objects</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#see_also">SEE ALSO</a></li>
  26         <li><a href="#history">HISTORY</a></li>
  27 </ul>
  28 <!-- INDEX END -->
  29
  30 <hr />
  31 <p>
  32 </p>
  33 <h1><a name="name">NAME</a></h1>
  34 <p>IO::Seekable - supply seek based methods for I/O objects</p>
  35 <p>
  36 </p>
  37 <hr />
  38 <h1><a name="synopsis">SYNOPSIS</a></h1>
  39 <pre>
  40     use IO::Seekable;
  41     package IO::Something;
  42     @ISA = qw(IO::Seekable);</pre>
  43 <p>
  44 </p>
  45 <hr />
  46 <h1><a name="description">DESCRIPTION</a></h1>
  47 <p><code>IO::Seekable</code> does not have a constructor of its own as it is intended to
  48 be inherited by other <code>IO::Handle</code> based objects. It provides methods
  49 which allow seeking of the file descriptors.</p>
  50 <dl>
  51 <dt><strong><a name="item_getpos">$io-&gt;getpos</a></strong>
  52
  53 <dd>
  54 <p>Returns an opaque value that represents the current position of the
  55 IO::File, or <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> if this is not possible (eg an unseekable stream such
  56 as a terminal, pipe or socket). If the <code>fgetpos()</code> function is available in
  57 your C library it is used to implements getpos, else perl emulates getpos
  58 using C's <code>ftell()</code> function.</p>
  59 </dd>
  60 </li>
  61 <dt><strong><a name="item_setpos">$io-&gt;setpos</a></strong>
  62
  63 <dd>
  64 <p>Uses the value of a previous getpos call to return to a previously visited
  65 position. Returns ``0 but true'' on success, <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> on failure.</p>
  66 </dd>
  67 </li>
  68 </dl>
  69 <p>See <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html">the perlfunc manpage</a> for complete descriptions of each of the following
  70 supported <code>IO::Seekable</code> methods, which are just front ends for the
  71 corresponding built-in functions:</p>
  72 <dl>
  73 <dt><strong><a name="item_seek">$io-&gt;seek ( POS, WHENCE )</a></strong>
  74
  75 <dd>
  76 <p>Seek the IO::File to position POS, relative to WHENCE:</p>
  77 </dd>
  78 <dl>
  79 <dt><strong><a name="item_0">WHENCE=0 (SEEK_SET)</a></strong>
  80
  81 <dd>
  82 <p>POS is absolute position. (Seek relative to the start of the file)</p>
  83 </dd>
  84 </li>
  85 <dt><strong><a name="item_1">WHENCE=1 (SEEK_CUR)</a></strong>
  86
  87 <dd>
  88 <p>POS is an offset from the current position. (Seek relative to current)</p>
  89 </dd>
  90 </li>
  91 <dt><strong><a name="item_2">WHENCE=2 (SEEK_END)</a></strong>
  92
  93 <dd>
  94 <p>POS is an offset from the end of the file. (Seek relative to end)</p>
  95 </dd>
  96 </li>
  97 </dl>
  98 <p>The SEEK_* constants can be imported from the <code>Fcntl</code> module if you
  99 don't wish to use the numbers <code>0</code> <a href="#item_1"><code>1</code></a> or <a href="#item_2"><code>2</code></a> in your code.</p>
 100 <p>Returns <a href="#item_1"><code>1</code></a> upon success, <code>0</code> otherwise.</p>
 101 <dt><strong><a name="item_sysseek">$io-&gt;sysseek( POS, WHENCE )</a></strong>
 102
 103 <dd>
 104 <p>Similar to $io-&gt;seek, but sets the IO::File's position using the system
 105 call <code>lseek(2)</code> directly, so will confuse most perl IO operators except
 106 sysread and syswrite (see <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html">the perlfunc manpage</a> for full details)</p>
 107 </dd>
 108 <dd>
 109 <p>Returns the new position, or <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_undef"><code>undef</code></a> on failure.  A position
 110 of zero is returned as the string <code>&quot;0 but true&quot;</code></p>
 111 </dd>
 112 </li>
 113 <dt><strong><a name="item_tell">$io-&gt;tell</a></strong>
 114
 115 <dd>
 116 <p>Returns the IO::File's current position, or -1 on error.</p>
 117 </dd>
 118 </li>
 119 </dl>
 120 <p>
 121 </p>
 122 <hr />
 123 <h1><a name="see_also">SEE ALSO</a></h1>
 124 <p><a href="file://C|\msysgit\mingw\html/pod/perlfunc.html">the perlfunc manpage</a>,
 125 <a href="file://C|\msysgit\mingw\html/pod/perlop.html#i_o_operators">I/O Operators in the perlop manpage</a>,
 126 <a href="file://C|\msysgit\mingw\html/lib/IO/Handle.html">the IO::Handle manpage</a>
 127 <a href="file://C|\msysgit\mingw\html/lib/IO/File.html">the IO::File manpage</a></p>
 128 <p>
 129 </p>
 130 <hr />
 131 <h1><a name="history">HISTORY</a></h1>
 132 <p>Derived from FileHandle.pm by Graham Barr &lt;<a href="mailto:gbarr@pobox.com">gbarr@pobox.com</a>&gt;</p>
 133 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 134 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 135 <big><strong><span class="block">&nbsp;IO::Seekable - supply seek based methods for I/O objects</span></strong></big>
 136 </td></tr>
 137 </table>
 138
 139 </body>
 140
 141 </html>