doc/xml/gnome-vfs-file-rw-ops.xml

   1 <refentry id="gnome-vfs-20-gnome-vfs-file-rw-ops">
   2 <refmeta>
   3 <refentrytitle>Reading and Writing</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>GNOME-VFS-2.0 Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Reading and Writing</refname><refpurpose></refpurpose>
  10 </refnamediv>
  11
  12 <refsynopsisdiv><title>Synopsis</title>
  13
  14 <synopsis>
  15
  16
  17
  18 enum        <link linkend="GnomeVFSSeekPosition">GnomeVFSSeekPosition</link>;
  19 <link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-read">gnome_vfs_read</link>               (<link linkend="GnomeVFSHandle">GnomeVFSHandle</link> *handle,
  20                                              <link linkend="gpointer">gpointer</link> buffer,
  21                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes,
  22                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *bytes_read);
  23 <link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-write">gnome_vfs_write</link>              (<link linkend="GnomeVFSHandle">GnomeVFSHandle</link> *handle,
  24                                              <link linkend="gconstpointer">gconstpointer</link> buffer,
  25                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes,
  26                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *bytes_written);
  27 <link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-seek">gnome_vfs_seek</link>               (<link linkend="GnomeVFSHandle">GnomeVFSHandle</link> *handle,
  28                                              <link linkend="GnomeVFSSeekPosition">GnomeVFSSeekPosition</link> whence,
  29                                              <link linkend="GnomeVFSFileOffset">GnomeVFSFileOffset</link> offset);
  30 <link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-tell">gnome_vfs_tell</link>               (<link linkend="GnomeVFSHandle">GnomeVFSHandle</link> *handle,
  31                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *offset_return);
  32 </synopsis>
  33 </refsynopsisdiv>
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43 <refsect1>
  44 <title>Description</title>
  45 <para>
  46   Reading and writing operations are explained, also <parameter>gnome_vfs_seek</parameter>, which
  47   is used to move the file pointer inside the file.
  48 </para>
  49 </refsect1>
  50
  51 <refsect1>
  52 <title>Details</title>
  53 <refsect2>
  54 <title><anchor id="GnomeVFSSeekPosition"/>enum GnomeVFSSeekPosition</title>
  55 <indexterm><primary>GnomeVFSSeekPosition</primary></indexterm><programlisting>typedef enum {
  56         GNOME_VFS_SEEK_START,
  57         GNOME_VFS_SEEK_CURRENT,
  58         GNOME_VFS_SEEK_END
  59 } GnomeVFSSeekPosition;
  60 </programlisting>
  61 <para>
  62 This is used to specify the start position for seek operations.</para>
  63 <para>
  64
  65 </para><variablelist role="enum">
  66 <varlistentry>
  67 <term><literal>GNOME_VFS_SEEK_START</literal></term>
  68 <listitem><simpara> Start of the file.
  69 </simpara></listitem>
  70 </varlistentry>
  71 <varlistentry>
  72 <term><literal>GNOME_VFS_SEEK_CURRENT</literal></term>
  73 <listitem><simpara> Current position.
  74 </simpara></listitem>
  75 </varlistentry>
  76 <varlistentry>
  77 <term><literal>GNOME_VFS_SEEK_END</literal></term>
  78 <listitem><simpara> End of the file.
  79 </simpara></listitem>
  80 </varlistentry>
  81 </variablelist></refsect2>
  82 <refsect2>
  83 <title><anchor id="gnome-vfs-read"/>gnome_vfs_read ()</title>
  84 <indexterm><primary>gnome_vfs_read</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_read               (<link linkend="GnomeVFSHandle">GnomeVFSHandle</link> *handle,
  85                                              <link linkend="gpointer">gpointer</link> buffer,
  86                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes,
  87                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *bytes_read);</programlisting>
  88 <para>
  89 Read <parameter>bytes</parameter> from <parameter>handle</parameter>.  As with Unix system calls, the number of
  90 bytes read can effectively be less than <parameter>bytes</parameter> on return and will be
  91 stored in <parameter>bytes_read</parameter>.</para>
  92 <para>
  93
  94 </para><variablelist role="params">
  95 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
  96 <listitem><simpara> Handle of the file to read data from
  97 </simpara></listitem></varlistentry>
  98 <varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
  99 <listitem><simpara> Pointer to a buffer that must be at least <parameter>bytes</parameter> bytes large
 100 </simpara></listitem></varlistentry>
 101 <varlistentry><term><parameter>bytes</parameter>&nbsp;:</term>
 102 <listitem><simpara> Number of bytes to read
 103 </simpara></listitem></varlistentry>
 104 <varlistentry><term><parameter>bytes_read</parameter>&nbsp;:</term>
 105 <listitem><simpara> Pointer to a variable that will hold the number of bytes
 106 effectively read on return.
 107 </simpara></listitem></varlistentry>
 108 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> An integer representing the result of the operation
 109 </simpara></listitem></varlistentry>
 110 </variablelist></refsect2>
 111 <refsect2>
 112 <title><anchor id="gnome-vfs-write"/>gnome_vfs_write ()</title>
 113 <indexterm><primary>gnome_vfs_write</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_write              (<link linkend="GnomeVFSHandle">GnomeVFSHandle</link> *handle,
 114                                              <link linkend="gconstpointer">gconstpointer</link> buffer,
 115                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> bytes,
 116                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *bytes_written);</programlisting>
 117 <para>
 118 Write <parameter>bytes</parameter> into the file opened through <parameter>handle</parameter>.  As with Unix system
 119 calls, the number of bytes written can effectively be less than <parameter>bytes</parameter> on
 120 return and will be stored in <parameter>bytes_written</parameter>.</para>
 121 <para>
 122
 123 </para><variablelist role="params">
 124 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
 125 <listitem><simpara> Handle of the file to write data to
 126 </simpara></listitem></varlistentry>
 127 <varlistentry><term><parameter>buffer</parameter>&nbsp;:</term>
 128 <listitem><simpara> Pointer to the buffer containing the data to be written
 129 </simpara></listitem></varlistentry>
 130 <varlistentry><term><parameter>bytes</parameter>&nbsp;:</term>
 131 <listitem><simpara> Number of bytes to write
 132 </simpara></listitem></varlistentry>
 133 <varlistentry><term><parameter>bytes_written</parameter>&nbsp;:</term>
 134 <listitem><simpara> Pointer to a variable that will hold the number of bytes
 135 effectively written on return.
 136 </simpara></listitem></varlistentry>
 137 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> An integer representing the result of the operation
 138 </simpara></listitem></varlistentry>
 139 </variablelist></refsect2>
 140 <refsect2>
 141 <title><anchor id="gnome-vfs-seek"/>gnome_vfs_seek ()</title>
 142 <indexterm><primary>gnome_vfs_seek</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_seek               (<link linkend="GnomeVFSHandle">GnomeVFSHandle</link> *handle,
 143                                              <link linkend="GnomeVFSSeekPosition">GnomeVFSSeekPosition</link> whence,
 144                                              <link linkend="GnomeVFSFileOffset">GnomeVFSFileOffset</link> offset);</programlisting>
 145 <para>
 146 Set the current position for reading/writing through <parameter>handle</parameter>.</para>
 147 <para>
 148
 149 </para><variablelist role="params">
 150 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
 151 <listitem><simpara> Handle for which the current position must be changed
 152 </simpara></listitem></varlistentry>
 153 <varlistentry><term><parameter>whence</parameter>&nbsp;:</term>
 154 <listitem><simpara> Integer value representing the starting position
 155 </simpara></listitem></varlistentry>
 156 <varlistentry><term><parameter>offset</parameter>&nbsp;:</term>
 157 <listitem><simpara> Number of bytes to skip from the position specified by <parameter>whence</parameter>
 158 (a positive value means to move forward; a negative one to move backwards)
 159 </simpara></listitem></varlistentry>
 160 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
 161 </simpara></listitem></varlistentry>
 162 </variablelist></refsect2>
 163 <refsect2>
 164 <title><anchor id="gnome-vfs-tell"/>gnome_vfs_tell ()</title>
 165 <indexterm><primary>gnome_vfs_tell</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_tell               (<link linkend="GnomeVFSHandle">GnomeVFSHandle</link> *handle,
 166                                              <link linkend="GnomeVFSFileSize">GnomeVFSFileSize</link> *offset_return);</programlisting>
 167 <para>
 168 Return the current position on <parameter>handle</parameter>. This is the point in the file
 169 pointed to by handle that reads and writes will occur on.</para>
 170 <para>
 171
 172 </para><variablelist role="params">
 173 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
 174 <listitem><simpara> Handle for which the current position must be retrieved
 175 </simpara></listitem></varlistentry>
 176 <varlistentry><term><parameter>offset_return</parameter>&nbsp;:</term>
 177 <listitem><simpara> Pointer to a variable that will contain the current position
 178 on return
 179 </simpara></listitem></varlistentry>
 180 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> An integer representing the result of the operation
 181 </simpara></listitem></varlistentry>
 182 </variablelist></refsect2>
 183
 184 </refsect1>
 185
 186
 187
 188
 189 </refentry>