1
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5
<title>Reading and Writing Files</title>
6
<meta name="generator" content="DocBook XSL Stylesheets V1.74.3">
7
<link rel="home" href="index.html" title="GnomeVFS - Filesystem Abstraction library">
8
<link rel="up" href="gnome-vfs-basic-file-ops.html" title="File Operations">
9
<link rel="prev" href="gnome-vfs-2.0-gnome-vfs-file-basic-ops.html" title="Basic File Operations">
10
<link rel="next" href="gnome-vfs-2.0-gnome-vfs-file-trunc-ops.html" title="Truncating Files">
11
<meta name="generator" content="GTK-Doc V1.12 (XML mode)">
12
<link rel="stylesheet" href="style.css" type="text/css">
13
<link rel="chapter" href="about.html" title="Introduction to GnomeVFS">
14
<link rel="chapter" href="data-types.html" title="Basic Data Types">
15
<link rel="chapter" href="gnome-vfs-basic-file-ops.html" title="File Operations">
16
<link rel="chapter" href="gnome-vfs-directory-ops.html" title="Directory-Specific Operations">
17
<link rel="chapter" href="gnome-vfs-file-and-dirs-ops.html" title="Advanced File/Directory Operations">
18
<link rel="chapter" href="gnome-vfs-file-async-ops.html" title="Asynchronous Operations">
19
<link rel="chapter" href="volumes.html" title="Volumes and Drives Handling">
20
<link rel="chapter" href="networking.html" title="Networking">
21
<link rel="chapter" href="mime-registry.html" title="MIME Registry">
22
<link rel="chapter" href="modules.html" title="Filesystem Modules">
24
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
25
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
27
<td><a accesskey="p" href="gnome-vfs-2.0-gnome-vfs-file-basic-ops.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
28
<td><a accesskey="u" href="gnome-vfs-basic-file-ops.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
29
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
30
<th width="100%" align="center">GnomeVFS - Filesystem Abstraction library</th>
31
<td><a accesskey="n" href="gnome-vfs-2.0-gnome-vfs-file-trunc-ops.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
33
<tr><td colspan="5" class="shortcuts">
34
<a href="#gnome-vfs-2.0-gnome-vfs-file-rw-ops.synopsis" class="shortcut">Top</a>
36
<a href="#gnome-vfs-2.0-gnome-vfs-file-rw-ops.description" class="shortcut">Description</a>
39
<div class="refentry" lang="en">
40
<a name="gnome-vfs-2.0-gnome-vfs-file-rw-ops"></a><div class="titlepage"></div>
41
<div class="refnamediv"><table width="100%"><tr>
43
<h2><span class="refentrytitle"><a name="gnome-vfs-2.0-gnome-vfs-file-rw-ops.top_of_page"></a>Reading and Writing Files</span></h2>
44
<p>Reading and Writing Files — Reading from and writing to open file handles.</p>
46
<td valign="top" align="right"></td>
48
<div class="refsynopsisdiv">
49
<a name="gnome-vfs-2.0-gnome-vfs-file-rw-ops.synopsis"></a><h2>Synopsis</h2>
50
<pre class="synopsis">
51
enum <a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#GnomeVFSSeekPosition" title="enum GnomeVFSSeekPosition">GnomeVFSSeekPosition</a>;
52
<a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult">GnomeVFSResult</a> <a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#gnome-vfs-read" title="gnome_vfs_read ()">gnome_vfs_read</a> (GnomeVFSHandle *handle,
54
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize">GnomeVFSFileSize</a> bytes,
55
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize">GnomeVFSFileSize</a> *bytes_read);
56
<a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult">GnomeVFSResult</a> <a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#gnome-vfs-write" title="gnome_vfs_write ()">gnome_vfs_write</a> (GnomeVFSHandle *handle,
58
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize">GnomeVFSFileSize</a> bytes,
59
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize">GnomeVFSFileSize</a> *bytes_written);
60
<a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult">GnomeVFSResult</a> <a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#gnome-vfs-seek" title="gnome_vfs_seek ()">gnome_vfs_seek</a> (GnomeVFSHandle *handle,
61
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#GnomeVFSSeekPosition" title="enum GnomeVFSSeekPosition">GnomeVFSSeekPosition</a> whence,
62
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileOffset" title="GnomeVFSFileOffset">GnomeVFSFileOffset</a> offset);
63
<a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult">GnomeVFSResult</a> <a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#gnome-vfs-tell" title="gnome_vfs_tell ()">gnome_vfs_tell</a> (GnomeVFSHandle *handle,
64
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize">GnomeVFSFileSize</a> *offset_return);
65
<a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult">GnomeVFSResult</a> <a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#gnome-vfs-forget-cache" title="gnome_vfs_forget_cache ()">gnome_vfs_forget_cache</a> (GnomeVFSHandle *handle,
66
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileOffset" title="GnomeVFSFileOffset">GnomeVFSFileOffset</a> offset,
67
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize">GnomeVFSFileSize</a> size);
70
<div class="refsect1" lang="en">
71
<a name="gnome-vfs-2.0-gnome-vfs-file-rw-ops.description"></a><h2>Description</h2>
73
Reading and writing operations are explained, also <a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#gnome-vfs-seek" title="gnome_vfs_seek ()"><code class="function">gnome_vfs_seek()</code></a>, which
74
is used to move the file pointer inside the file.
77
<div class="refsect1" lang="en">
78
<a name="gnome-vfs-2.0-gnome-vfs-file-rw-ops.details"></a><h2>Details</h2>
79
<div class="refsect2" lang="en">
80
<a name="GnomeVFSSeekPosition"></a><h3>enum GnomeVFSSeekPosition</h3>
81
<pre class="programlisting">typedef enum {
83
GNOME_VFS_SEEK_CURRENT,
85
} GnomeVFSSeekPosition;
88
This is used to specify the start position for seek operations.</p>
91
<div class="variablelist"><table border="0">
92
<col align="left" valign="top">
95
<td><p><a name="GNOME-VFS-SEEK-START:CAPS"></a><span class="term"><code class="literal">GNOME_VFS_SEEK_START</code></span></p></td>
96
<td> Start of the file.
100
<td><p><a name="GNOME-VFS-SEEK-CURRENT:CAPS"></a><span class="term"><code class="literal">GNOME_VFS_SEEK_CURRENT</code></span></p></td>
101
<td> Current position.
105
<td><p><a name="GNOME-VFS-SEEK-END:CAPS"></a><span class="term"><code class="literal">GNOME_VFS_SEEK_END</code></span></p></td>
106
<td> End of the file.
113
<div class="refsect2" lang="en">
114
<a name="gnome-vfs-read"></a><h3>gnome_vfs_read ()</h3>
115
<pre class="programlisting"><a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult">GnomeVFSResult</a> gnome_vfs_read (GnomeVFSHandle *handle,
117
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize">GnomeVFSFileSize</a> bytes,
118
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize">GnomeVFSFileSize</a> *bytes_read);</pre>
120
Read <em class="parameter"><code>bytes</code></em> from <em class="parameter"><code>handle</code></em>. As with Unix system calls, the number of
121
bytes read can effectively be less than <em class="parameter"><code>bytes</code></em> on return and will be
122
stored in <em class="parameter"><code>bytes_read</code></em>.</p>
125
<div class="variablelist"><table border="0">
126
<col align="left" valign="top">
129
<td><p><span class="term"><em class="parameter"><code>handle</code></em> :</span></p></td>
130
<td> handle of the file to read data from.
134
<td><p><span class="term"><em class="parameter"><code>buffer</code></em> :</span></p></td>
135
<td> pointer to a buffer that must be at least <em class="parameter"><code>bytes</code></em> bytes large.
139
<td><p><span class="term"><em class="parameter"><code>bytes</code></em> :</span></p></td>
140
<td> number of bytes to read.
144
<td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
145
<td> pointer to a variable that will hold the number of bytes
146
effectively read on return.
150
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
151
<td> an integer representing the result of the operation.
158
<div class="refsect2" lang="en">
159
<a name="gnome-vfs-write"></a><h3>gnome_vfs_write ()</h3>
160
<pre class="programlisting"><a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult">GnomeVFSResult</a> gnome_vfs_write (GnomeVFSHandle *handle,
161
gconstpointer buffer,
162
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize">GnomeVFSFileSize</a> bytes,
163
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize">GnomeVFSFileSize</a> *bytes_written);</pre>
165
Write <em class="parameter"><code>bytes</code></em> into the file opened through <em class="parameter"><code>handle</code></em>. As with Unix system
166
calls, the number of bytes written can effectively be less than <em class="parameter"><code>bytes</code></em> on
167
return and will be stored in <em class="parameter"><code>bytes_written</code></em>.</p>
170
<div class="variablelist"><table border="0">
171
<col align="left" valign="top">
174
<td><p><span class="term"><em class="parameter"><code>handle</code></em> :</span></p></td>
175
<td> handle of the file to write data to.
179
<td><p><span class="term"><em class="parameter"><code>buffer</code></em> :</span></p></td>
180
<td> pointer to the buffer containing the data to be written.
184
<td><p><span class="term"><em class="parameter"><code>bytes</code></em> :</span></p></td>
185
<td> number of bytes to write.
189
<td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
190
<td> pointer to a variable that will hold the number of bytes
191
effectively written on return.
195
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
196
<td> an integer representing the result of the operation.
203
<div class="refsect2" lang="en">
204
<a name="gnome-vfs-seek"></a><h3>gnome_vfs_seek ()</h3>
205
<pre class="programlisting"><a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult">GnomeVFSResult</a> gnome_vfs_seek (GnomeVFSHandle *handle,
206
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-rw-ops.html#GnomeVFSSeekPosition" title="enum GnomeVFSSeekPosition">GnomeVFSSeekPosition</a> whence,
207
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileOffset" title="GnomeVFSFileOffset">GnomeVFSFileOffset</a> offset);</pre>
209
Set the current position for reading/writing through <em class="parameter"><code>handle</code></em>.</p>
212
<div class="variablelist"><table border="0">
213
<col align="left" valign="top">
216
<td><p><span class="term"><em class="parameter"><code>handle</code></em> :</span></p></td>
217
<td> handle for which the current position must be changed.
221
<td><p><span class="term"><em class="parameter"><code>whence</code></em> :</span></p></td>
222
<td> integer value representing the starting position.
226
<td><p><span class="term"><em class="parameter"><code>offset</code></em> :</span></p></td>
227
<td> number of bytes to skip from the position specified by <em class="parameter"><code>whence</code></em>.
228
(a positive value means to move forward; a negative one to move backwards).
232
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
233
<td> an integer representing the result of the operation.
240
<div class="refsect2" lang="en">
241
<a name="gnome-vfs-tell"></a><h3>gnome_vfs_tell ()</h3>
242
<pre class="programlisting"><a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult">GnomeVFSResult</a> gnome_vfs_tell (GnomeVFSHandle *handle,
243
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize">GnomeVFSFileSize</a> *offset_return);</pre>
245
Return the current position on <em class="parameter"><code>handle</code></em>. This is the point in the file
246
pointed to by handle that reads and writes will occur on.</p>
249
<div class="variablelist"><table border="0">
250
<col align="left" valign="top">
253
<td><p><span class="term"><em class="parameter"><code>handle</code></em> :</span></p></td>
254
<td> handle for which the current position must be retrieved.
258
<td><p><span class="term"><em class="parameter"><code>offset_return</code></em> :</span></p></td>
259
<td> pointer to a variable that will contain the current position
264
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
265
<td> an integer representing the result of the operation.
272
<div class="refsect2" lang="en">
273
<a name="gnome-vfs-forget-cache"></a><h3>gnome_vfs_forget_cache ()</h3>
274
<pre class="programlisting"><a class="link" href="gnome-vfs-2.0-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult">GnomeVFSResult</a> gnome_vfs_forget_cache (GnomeVFSHandle *handle,
275
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileOffset" title="GnomeVFSFileOffset">GnomeVFSFileOffset</a> offset,
276
<a class="link" href="gnome-vfs-2.0-gnome-vfs-file-size.html#GnomeVFSFileSize" title="GnomeVFSFileSize">GnomeVFSFileSize</a> size);</pre>
278
With this call you can announce to gnome-vfs that you will no longer
279
use the region of data starting at <em class="parameter"><code>offset</code></em> with the size of <em class="parameter"><code>size</code></em>. Any
280
cached data for this region might then be freed.
283
This might be useful if you stream large files, for example.</p>
286
<div class="variablelist"><table border="0">
287
<col align="left" valign="top">
290
<td><p><span class="term"><em class="parameter"><code>handle</code></em> :</span></p></td>
291
<td> handle of the file to affect.
295
<td><p><span class="term"><em class="parameter"><code>offset</code></em> :</span></p></td>
296
<td> start point of the region to be freed.
300
<td><p><span class="term"><em class="parameter"><code>size</code></em> :</span></p></td>
301
<td> length of the region to be freed (or until the end of the
302
file if 0 is specified).
306
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
307
<td> an integer representing the result of the operation.
313
<p class="since">Since 2.12</p>
319
Generated by GTK-Doc V1.12</div>
added
removed
doc/html/gnome-vfs-2.0-gnome-vfs-file-rw-ops.html
