1ZFILE(3) CZMQ Manual ZFILE(3)
2
6 zfile - provides methods to work with files in a portable fashion.
7
9 // This is a stable class, and may not change except for emergencies. It
10 // is provided in stable builds.
11 // If file exists, populates properties. CZMQ supports portable symbolic
12 // links, which are files with the extension ".ln". A symbolic link is a
13 // text file containing one line, the filename of a target file. Reading
14 // data from the symbolic link actually reads from the target file. Path
15 // may be NULL, in which case it is not used.
16 CZMQ_EXPORT zfile_t *
17 zfile_new (const char *path, const char *name);
18 // Destroy a file item
20 CZMQ_EXPORT void
21 zfile_destroy (zfile_t **self_p);
22 // Duplicate a file item, returns a newly constructed item. If the file
24 // is null, or memory was exhausted, returns null.
25 // Caller owns return value and must destroy it when done.
26 CZMQ_EXPORT zfile_t *
27 zfile_dup (zfile_t *self);
28 // Return file name, remove path if provided
30 CZMQ_EXPORT const char *
31 zfile_filename (zfile_t *self, const char *path);
32 // Refresh file properties from disk; this is not done automatically
34 // on access methods, otherwise it is not possible to compare directory
35 // snapshots.
36 CZMQ_EXPORT void
37 zfile_restat (zfile_t *self);
38 // Return when the file was last modified. If you want this to reflect the
40 // current situation, call zfile_restat before checking this property.
41 CZMQ_EXPORT time_t
42 zfile_modified (zfile_t *self);
43 // Return the last-known size of the file. If you want this to reflect the
45 // current situation, call zfile_restat before checking this property.
46 CZMQ_EXPORT off_t
47 zfile_cursize (zfile_t *self);
48 // Return true if the file is a directory. If you want this to reflect
50 // any external changes, call zfile_restat before checking this property.
51 CZMQ_EXPORT bool
52 zfile_is_directory (zfile_t *self);
53 // Return true if the file is a regular file. If you want this to reflect
55 // any external changes, call zfile_restat before checking this property.
56 CZMQ_EXPORT bool
57 zfile_is_regular (zfile_t *self);
58 // Return true if the file is readable by this process. If you want this to
60 // reflect any external changes, call zfile_restat before checking this
61 // property.
62 CZMQ_EXPORT bool
63 zfile_is_readable (zfile_t *self);
64 // Return true if the file is writeable by this process. If you want this
66 // to reflect any external changes, call zfile_restat before checking this
67 // property.
68 CZMQ_EXPORT bool
69 zfile_is_writeable (zfile_t *self);
70 // Check if file has stopped changing and can be safely processed.
72 // Updates the file statistics from disk at every call.
73 CZMQ_EXPORT bool
74 zfile_is_stable (zfile_t *self);
75 // Return true if the file was changed on disk since the zfile_t object
77 // was created, or the last zfile_restat() call made on it.
78 CZMQ_EXPORT bool
79 zfile_has_changed (zfile_t *self);
80 // Remove the file from disk
82 CZMQ_EXPORT void
83 zfile_remove (zfile_t *self);
84 // Open file for reading
86 // Returns 0 if OK, -1 if not found or not accessible
87 CZMQ_EXPORT int
88 zfile_input (zfile_t *self);
89 // Open file for writing, creating directory if needed
91 // File is created if necessary; chunks can be written to file at any
92 // location. Returns 0 if OK, -1 if error.
93 CZMQ_EXPORT int
94 zfile_output (zfile_t *self);
95 // Read chunk from file at specified position. If this was the last chunk,
97 // sets the eof property. Returns a null chunk in case of error.
98 // Caller owns return value and must destroy it when done.
99 CZMQ_EXPORT zchunk_t *
100 zfile_read (zfile_t *self, size_t bytes, off_t offset);
101 // Returns true if zfile_read() just read the last chunk in the file.
103 CZMQ_EXPORT bool
104 zfile_eof (zfile_t *self);
105 // Write chunk to file at specified position
107 // Return 0 if OK, else -1
108 CZMQ_EXPORT int
109 zfile_write (zfile_t *self, zchunk_t *chunk, off_t offset);
110 // Read next line of text from file. Returns a pointer to the text line,
112 // or NULL if there was nothing more to read from the file.
113 CZMQ_EXPORT const char *
114 zfile_readln (zfile_t *self);
115 // Close file, if open
117 CZMQ_EXPORT void
118 zfile_close (zfile_t *self);
119 // Return file handle, if opened
121 CZMQ_EXPORT FILE *
122 zfile_handle (zfile_t *self);
123 // Calculate SHA1 digest for file, using zdigest class.
125 CZMQ_EXPORT const char *
126 zfile_digest (zfile_t *self);
127 // Self test of this class.
129 CZMQ_EXPORT void
130 zfile_test (bool verbose);
131 // These methods are deprecated, and now moved to zsys class.
133 CZMQ_EXPORT bool
134 zfile_exists (const char *filename);
135 CZMQ_EXPORT ssize_t
136 zfile_size (const char *filename);
137 CZMQ_EXPORT mode_t
138 zfile_mode (const char *filename);
139 CZMQ_EXPORT int
140 zfile_delete (const char *filename);
141 CZMQ_EXPORT bool
142 zfile_stable (const char *filename);
143 CZMQ_EXPORT int
144 zfile_mkdir (const char *pathname);
145 CZMQ_EXPORT int
146 zfile_rmdir (const char *pathname);
147 CZMQ_EXPORT void
148 zfile_mode_private (void);
149 CZMQ_EXPORT void
150 zfile_mode_default (void);
151 Please add '@interface' section in './../src/zfile.c'.
152
154 The zfile class provides methods to work with disk files. A file object
155 provides the modified date, current size, and type of the file. You can
156 create a file object for a filename that does not yet exist. To read or
157 write data from the file, use the input and output methods, and then
158 read and write chunks. The output method lets you both read and write
159 chunks, at any offset. Finally, this class provides portable symbolic
160 links. If a filename ends in ".ln", the first line of text in the file
161 is read, and used as the underlying file for read/write operations.
162 This lets you manipulate (e.g.) copy symbolic links without copying the
163 perhaps very large files they point to.
164 This class is a new API, deprecating the old zfile class (which still
166 exists but is implemented in zsys now).
167
169 From zfile_test method.
170 zfile_t *file = zfile_new (NULL, "bilbo");
172 assert (file);
173 assert (streq (zfile_filename (file, "."), "bilbo"));
174 assert (zfile_is_readable (file) == false);
175 zfile_destroy (&file);
176 // Create a test file in some random subdirectory
178 file = zfile_new ("./this/is/a/test", "bilbo");
179 assert (file);
180 int rc = zfile_output (file);
181 assert (rc == 0);
182 zchunk_t *chunk = zchunk_new (NULL, 100);
183 assert (chunk);
184 zchunk_fill (chunk, 0, 100);
185 // Write 100 bytes at position 1,000,000 in the file
187 rc = zfile_write (file, chunk, 1000000);
188 assert (rc == 0);
189 zchunk_destroy (&chunk);
190 zfile_close (file);
191 assert (zfile_is_readable (file));
192 assert (zfile_cursize (file) == 1000100);
193 assert (!zfile_is_stable (file));
194 assert (zfile_digest (file));
195 // Now truncate file from outside
197 int handle = open ("./this/is/a/test/bilbo", O_WRONLY | O_TRUNC | O_BINARY, 0);
198 assert (handle >= 0);
199 rc = write (handle, "Hello, World\n", 13);
200 assert (rc == 13);
201 close (handle);
202 assert (zfile_has_changed (file));
203 zclock_sleep (1001);
204 assert (zfile_has_changed (file));
205 assert (!zfile_is_stable (file));
207 zfile_restat (file);
208 assert (zfile_is_stable (file));
209 assert (streq (zfile_digest (file), "4AB299C8AD6ED14F31923DD94F8B5F5CB89DFB54"));
210 // Check we can read from file
212 rc = zfile_input (file);
213 assert (rc == 0);
214 chunk = zfile_read (file, 1000100, 0);
215 assert (chunk);
216 assert (zchunk_size (chunk) == 13);
217 zchunk_destroy (&chunk);
218 zfile_close (file);
219 // Check we can read lines from file
221 rc = zfile_input (file);
222 assert (rc == 0);
223 const char *line = zfile_readln (file);
224 assert (streq (line, "Hello, World"));
225 line = zfile_readln (file);
226 assert (line == NULL);
227 zfile_close (file);
228 // Try some fun with symbolic links
230 zfile_t *link = zfile_new ("./this/is/a/test", "bilbo.ln");
231 assert (link);
232 rc = zfile_output (link);
233 assert (rc == 0);
234 fprintf (zfile_handle (link), "./this/is/a/test/bilbo\n");
235 zfile_destroy (&link);
236 link = zfile_new ("./this/is/a/test", "bilbo.ln");
238 assert (link);
239 rc = zfile_input (link);
240 assert (rc == 0);
241 chunk = zfile_read (link, 1000100, 0);
242 assert (chunk);
243 assert (zchunk_size (chunk) == 13);
244 zchunk_destroy (&chunk);
245 zfile_destroy (&link);
246 // Remove file and directory
248 zdir_t *dir = zdir_new ("./this", NULL);
249 assert (dir);
250 assert (zdir_cursize (dir) == 26);
251 zdir_remove (dir, true);
252 assert (zdir_cursize (dir) == 0);
253 zdir_destroy (&dir);
254 // Check we can no longer read from file
256 assert (zfile_is_readable (file));
257 zfile_restat (file);
258 assert (!zfile_is_readable (file));
259 rc = zfile_input (file);
260 assert (rc == -1);
261 zfile_destroy (&file);
262 file = zfile_new ("./", "eof_checkfile");
264 assert (file);
265 // 1. Write something first
266 rc = zfile_output (file);
267 assert (rc == 0);
268 chunk = zchunk_new ("123456789", 9);
269 assert (chunk);
270 rc = zfile_write (file, chunk, 0);
272 assert (rc == 0);
273 zchunk_destroy (&chunk);
274 zfile_close (file);
275 assert (zfile_cursize (file) == 9);
276 // 2. Read the written something
278 rc = zfile_input (file);
279 assert (rc != -1);
280 // try to read more bytes than there is in the file
281 chunk = zfile_read (file, 1000, 0);
282 assert (zfile_eof(file));
283 assert (zchunk_streq (chunk, "123456789"));
284 zchunk_destroy (&chunk);
285 // reading is ok
287 chunk = zfile_read (file, 5, 0);
288 assert (!zfile_eof(file));
289 assert (zchunk_streq (chunk, "12345"));
290 zchunk_destroy (&chunk);
291 // read from non zero offset until the end
293 chunk = zfile_read (file, 5, 5);
294 assert (zfile_eof(file));
295 assert (zchunk_streq (chunk, "6789"));
296 zchunk_destroy (&chunk);
297 zfile_remove (file);
298
301 The czmq manual was written by the authors in the AUTHORS file.
302
304 Main web site:
305 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
307
309 Copyright (c) the Contributors as noted in the AUTHORS file. This file
310 is part of CZMQ, the high-level C binding for 0MQ:
311 http://czmq.zeromq.org. This Source Code Form is subject to the terms
312 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
313 distributed with this file, You can obtain one at
314 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
315 distribution.
316
318 1. zeromq-dev@lists.zeromq.org
319 mailto:zeromq-dev@lists.zeromq.org
320CZMQ 4.0.2 12/31/2016 ZFILE(3)