autodoc.git/ traditional_manual/ chapter_9.html

Branch: Tag:

2003-10-15

2003-10-15 16:57:59 by Martin Stjernholm <mast@lysator.liu.se>

Improved the doc some more.

Rev: src/modules/files/file.c:1.296

124:   <dd class='body--doc'><p>Close a file or stream.</p>   <p> If direction is not specified, both the read and the write direction    will be closed. Otherwise only the directions specified will be closed.</p> - <p> An exception is thrown if an I/O error occurs.</p> +    </dd>   <dt class='head--doc'>Returns</dt>   <dd class='body--doc'><p>Nonzero is returned if the file or stream wasn't open in the    specified direction, zero otherwise.</p>   </dd> -  + <dt class='head--doc'>Throws</dt> + <dd class='body--doc'><p>An exception is thrown if an I/O error occurs.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p><code>close()</code> has no effect if this file object has been associated +  with an already opened file, i.e. if <code>open()</code> was given an +  integer as the first argument.</p> + </dd>   <dt class='head--doc'>See also</dt>   <dd class='body--doc'><p><code>open()</code>, <code>open_socket()</code></p>   </dd></dl>
500:   <code><code class='datatype'>int</code> <b><span class='method'>open</span>(</b><code class='datatype'>int</code> <code class='argument'>fd</code>, <code class='datatype'>string</code> <code class='argument'>mode</code><b>)</b></code></p></dd>      <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Open a file or fd.</p> - <p> If <code>access</code> is not specified, it will default to <code class='expr'>00666</code>.</p> + <dd class='body--doc'><p>Open a file, or use an existing fd.</p> + <p> If <code>filename</code> is given, attempt to open the named file. If <code>fd</code> +  is given instead, it should be the file descriptor for an already +  opened file, which will then be used by this object.</p> + <p> <code>mode</code> describes how the file will be opened. It's a +  case-insensitive string consisting of one or more of the following +  letters:</p> + <dl class='group--doc'><dt>"r"</dt> + <dd><p>Open for reading.</p>   </dd> -  + <dt>"w"</dt> + <dd><p>Open for writing.</p> + </dd> + <dt>"a"</dt> + <dd><p>Append new data to the end.</p> + </dd> + <dt>"c"</dt> + <dd><p>Create the file if it doesn't exist already.</p> + </dd> + <dt>"t"</dt> + <dd><p>Truncate the file to zero length if it already contains data. +  Use only together with <code class='expr'>"w"</code>.</p> + </dd> + <dt>"x"</dt> + <dd><p>Open exclusively - the open will fail if the file already +  exists. Use only together with <code class='expr'>"c"</code>. Note that it's not +  safe to assume that this is atomic on some systems.</p> + </dd> + </dl><p><code>access</code> specifies the permissions to use if a new file is +  created. It is a UNIX style permission bitfield:</p> + <dl class='group--doc'><dt>0400</dt> + <dd><p>User has read permission.</p> + </dd> + <dt>0200</dt> + <dd><p>User has write permission.</p> + </dd> + <dt>0100</dt> + <dd><p>User has execute permission.</p> + </dd> + <dt>0040</dt> + <dd><p>Group has read permission.</p> + </dd> + <dt>0020</dt> + <dd><p>Group has write permission.</p> + </dd> + <dt>0010</dt> + <dd><p>Group has execute permission.</p> + </dd> + <dt>0004</dt> + <dd><p>Others have read permission.</p> + </dd> + <dt>0002</dt> + <dd><p>Others have write permission.</p> + </dd> + <dt>0001</dt> + <dd><p>Others have execute permission.</p> + </dd> + </dl><p>It's system dependent on which of these bits that are actually +  heeded. If <code>access</code> is not specified, it will default to +  <code class='expr'>00666</code>, but note that on UNIX systems it's masked with the +  process umask before use.</p> + </dd>   <dt class='head--doc'>See also</dt>   <dd class='body--doc'><p><code>close()</code></p>   </dd></dl>
817:   <code><code class='datatype'>string</code> <b><span class='method'>read</span>(</b><code class='datatype'>int</code> <code class='argument'>len</code>, <code class='datatype'>bool</code> <code class='argument'>not_all</code><b>)</b></code></p></dd>      <dt class='head--doc'>Description</dt> - <dd class='body--doc'><p>Read data from a file or a socket.</p> + <dd class='body--doc'><p>Read data from a file or a stream.</p>   <p> Attempts to read <code>len</code> bytes from the file, and return it as a -  string. Less than <code>len</code> bytes can be returned if end-of-file is -  encountered or, in the case it's a socket or pipe, it was closed -  from the other end.</p> - <p> If <code>not_all</code> is nonzero, <code>read()</code> will not try its best to read +  string. Less than <code>len</code> bytes can be returned if</p> + <ul> + <li><p>end-of-file is encountered for a normal file, or</p> + </li><li><p>it's a socket or pipe that has been closed from the other end, or</p> + </li><li><p>nonblocking mode is used.</p> + </li></ul><p>If <code>not_all</code> is nonzero, <code>read()</code> will not try its best to read    as many bytes as you have asked for, but will merely return as    much as the system read function will return. This mainly useful    with stream devices which can return exactly one row or packet at    a time.</p>   <p> If something goes wrong and <code>not_all</code> is set, zero will be -  returned. If something goes wrong and <code>not_all</code> is not set, then -  either zero or a string shorter than <code>len</code> is returned.</p> +  returned. If something goes wrong and <code>not_all</code> is not set, +  either zero or a string shorter than <code>len</code> is returned. If the +  problem persists then a later call to <code>read()</code> will fail and +  return zero, however.</p>   <p> If everything went fine, a call to <code>errno()</code> directly afterwards    will return zero. That includes an end due to end-of-file or    remote close.</p>   <p> If no arguments are given, <code>read()</code> will read to the -  end of the file/stream.</p> +  end of the file or stream.</p>   </dd> -  + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>It's not necessary to set <code>not_all</code> to avoid blocking reading +  when nonblocking mode is used.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>When at the end of a file or stream, repeated calls to <code>read()</code> +  will return the empty string since it's not considered an error. +  The empty string is never returned in other cases, unless +  nonblocking mode is used or <code>len</code> is zero.</p> + </dd>   <dt class='head--doc'>See also</dt>   <dd class='body--doc'><p><code>read_oob()</code>, <code>write()</code></p>   </dd></dl>
1386:   <p> -1 is returned if something went wrong and no bytes were written.</p>   </dd>   <dt class='head--doc'>Note</dt> - <dd class='body--doc'><p>Writing of wide strings is not supported.</p> + <dd class='body--doc'><p>Writing of wide strings is not supported. You have to encode the +  data somehow, e.g. with <code>string_to_utf8</code> or with one of the +  charsets supported by <code>Locale.Charset.encoder</code>.</p>   </dd>   <dt class='head--doc'>See also</dt>   <dd class='body--doc'><p><code>read()</code>, <code>write_oob()</code></p>