LRN: make disk iterator start return GNUNET_SYSERR if run on empty directory
[oweals/gnunet.git] / src / include / gnunet_disk_lib.h
1 /*
2      This file is part of GNUnet.
3      (C) 2001, 2002, 2003, 2004, 2005, 2006, 2009 Christian Grothoff (and other contributing authors)
4
5      GNUnet is free software; you can redistribute it and/or modify
6      it under the terms of the GNU General Public License as published
7      by the Free Software Foundation; either version 2, or (at your
8      option) any later version.
9
10      GNUnet is distributed in the hope that it will be useful, but
11      WITHOUT ANY WARRANTY; without even the implied warranty of
12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13      General Public License for more details.
14
15      You should have received a copy of the GNU General Public License
16      along with GNUnet; see the file COPYING.  If not, write to the
17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18      Boston, MA 02111-1307, USA.
19 */
20
21 /**
22  * @file include/gnunet_disk_lib.h
23  * @brief disk IO apis
24  */
25 #ifndef GNUNET_DISK_LIB_H
26 #define GNUNET_DISK_LIB_H
27
28 #if WINDOWS
29 #define OFF_T uint64_t
30 #else
31 #define OFF_T off_t
32 #endif
33
34 /**
35  * Opaque handle used to access files.
36  */
37 struct GNUNET_DISK_FileHandle;
38
39 /**
40  * Handle used to manage a pipe.
41  */
42 struct GNUNET_DISK_PipeHandle;
43
44
45 enum GNUNET_FILE_Type
46 {
47   GNUNET_DISK_FILE, GNUNET_PIPE
48 };
49
50 /**
51  * Handle used to access files (and pipes).
52  */
53 struct GNUNET_DISK_FileHandle
54 {
55
56 #if WINDOWS
57   /**
58    * File handle under W32.
59    */
60   HANDLE h;
61
62   /**
63    * Type
64    */
65   enum GNUNET_FILE_Type type;
66
67   /**
68    * Structure for overlapped reading (for pipes)
69    */
70   OVERLAPPED *oOverlapRead;
71
72   /**
73    * Structure for overlapped writing (for pipes)
74    */
75   OVERLAPPED *oOverlapWrite;
76 #else
77
78   /**
79    * File handle on other OSes.
80    */
81   int fd;
82
83 #endif                          /*
84                                  */
85 };
86
87
88 /* we need size_t, and since it can be both unsigned int
89    or unsigned long long, this IS platform dependent;
90    but "stdlib.h" should be portable 'enough' to be
91    unconditionally available... */
92 #include <stdlib.h>
93 #include "gnunet_configuration_lib.h"
94 #include "gnunet_scheduler_lib.h"
95
96 #ifdef __cplusplus
97 extern "C"
98 {
99 #if 0                           /* keep Emacsens' auto-indent happy */
100 }
101 #endif
102 #endif
103
104
105 /**
106  * Specifies how a file should be opened.
107  */
108 enum GNUNET_DISK_OpenFlags
109 {
110
111     /**
112      * Open the file for reading
113      */
114   GNUNET_DISK_OPEN_READ = 1,
115
116     /**
117      * Open the file for writing
118      */
119   GNUNET_DISK_OPEN_WRITE = 2,
120
121     /**
122      * Open the file for both reading and writing
123      */
124   GNUNET_DISK_OPEN_READWRITE = 3,
125
126     /**
127      * Fail if file already exists
128      */
129   GNUNET_DISK_OPEN_FAILIFEXISTS = 4,
130
131     /**
132      * Truncate file if it exists
133      */
134   GNUNET_DISK_OPEN_TRUNCATE = 8,
135
136     /**
137      * Create file if it doesn't exist
138      */
139   GNUNET_DISK_OPEN_CREATE = 16,
140
141     /**
142      * Append to the file
143      */
144   GNUNET_DISK_OPEN_APPEND = 32
145 };
146
147 /**
148  * Specifies what type of memory map is desired.
149  */
150 enum GNUNET_DISK_MapType
151 {
152     /**
153      * Read-only memory map.
154      */
155   GNUNET_DISK_MAP_TYPE_READ = 1,
156
157     /**
158      * Write-able memory map.
159      */
160   GNUNET_DISK_MAP_TYPE_WRITE = 2,
161     /**
162      * Read-write memory map.
163      */
164   GNUNET_DISK_MAP_TYPE_READWRITE = 3
165 };
166
167
168 /**
169  * File access permissions, UNIX-style.
170  */
171 enum GNUNET_DISK_AccessPermissions
172 {
173     /**
174      * Nobody is allowed to do anything to the file.
175      */
176   GNUNET_DISK_PERM_NONE = 0,
177
178     /**
179      * Owner can read.
180      */
181   GNUNET_DISK_PERM_USER_READ = 1,
182
183     /**
184      * Owner can write.
185      */
186   GNUNET_DISK_PERM_USER_WRITE = 2,
187
188     /**
189      * Owner can execute.
190      */
191   GNUNET_DISK_PERM_USER_EXEC = 4,
192
193     /**
194      * Group can read.
195      */
196   GNUNET_DISK_PERM_GROUP_READ = 8,
197
198     /**
199      * Group can write.
200      */
201   GNUNET_DISK_PERM_GROUP_WRITE = 16,
202
203     /**
204      * Group can execute.
205      */
206   GNUNET_DISK_PERM_GROUP_EXEC = 32,
207
208     /**
209      * Everybody can read.
210      */
211   GNUNET_DISK_PERM_OTHER_READ = 64,
212
213     /**
214      * Everybody can write.
215      */
216   GNUNET_DISK_PERM_OTHER_WRITE = 128,
217
218     /**
219      * Everybody can execute.
220      */
221   GNUNET_DISK_PERM_OTHER_EXEC = 256
222 };
223
224
225 /**
226  * Constants for specifying how to seek.
227  */
228 enum GNUNET_DISK_Seek
229 {
230     /**
231      * Seek an absolute position (from the start of the file).
232      */
233   GNUNET_DISK_SEEK_SET,
234
235     /**
236      * Seek a relative position (from the current offset).
237      */
238   GNUNET_DISK_SEEK_CUR,
239
240     /**
241      * Seek an absolute position from the end of the file.
242      */
243   GNUNET_DISK_SEEK_END
244 };
245
246
247 /**
248  * Enumeration identifying the two ends of a pipe.
249  */
250 enum GNUNET_DISK_PipeEnd
251 {
252     /**
253      * The reading-end of a pipe.
254      */
255   GNUNET_DISK_PIPE_END_READ = 0,
256
257     /**
258      * The writing-end of a pipe.
259      */
260   GNUNET_DISK_PIPE_END_WRITE = 1
261 };
262
263
264 /**
265  * Get the number of blocks that are left on the partition that
266  * contains the given file (for normal users).
267  *
268  * @param part a file on the partition to check
269  * @return -1 on errors, otherwise the number of free blocks
270  */
271 long
272 GNUNET_DISK_get_blocks_available (const char *part);
273
274
275 /**
276  * Checks whether a handle is invalid
277  *
278  * @param h handle to check
279  * @return GNUNET_YES if invalid, GNUNET_NO if valid
280  */
281 int
282 GNUNET_DISK_handle_invalid (const struct GNUNET_DISK_FileHandle *h);
283
284
285 /**
286  * Check that fil corresponds to a filename
287  * (of a file that exists and that is not a directory).
288  *
289  * @param fil filename to check
290  * @return GNUNET_YES if yes, GNUNET_NO if not a file, GNUNET_SYSERR if something
291  * else (will print an error message in that case, too).
292  */
293 int
294 GNUNET_DISK_file_test (const char *fil);
295
296
297 /**
298  * Move the read/write pointer in a file
299  * @param h handle of an open file
300  * @param offset position to move to
301  * @param whence specification to which position the offset parameter relates to
302  * @return the new position on success, GNUNET_SYSERR otherwise
303  */
304 OFF_T
305 GNUNET_DISK_file_seek (const struct GNUNET_DISK_FileHandle *h, OFF_T offset,
306                        enum GNUNET_DISK_Seek whence);
307
308
309 /**
310  * Get the size of the file (or directory)
311  * of the given file (in bytes).
312  *
313  * @param filename name of the file or directory
314  * @param size set to the size of the file (or,
315  *             in the case of directories, the sum
316  *             of all sizes of files in the directory)
317  * @param includeSymLinks should symbolic links be
318  *        included?
319  * @return GNUNET_OK on success, GNUNET_SYSERR on error
320  */
321 int
322 GNUNET_DISK_file_size (const char *filename, uint64_t * size,
323                        int includeSymLinks);
324
325
326 /**
327  * Obtain some unique identifiers for the given file
328  * that can be used to identify it in the local system.
329  * This function is used between GNUnet processes to
330  * quickly check if two files with the same absolute path
331  * are actually identical.  The two processes represent
332  * the same peer but may communicate over the network
333  * (and the file may be on an NFS volume).  This function
334  * may not be supported on all operating systems.
335  *
336  * @param filename name of the file
337  * @param dev set to the device ID
338  * @param ino set to the inode ID
339  * @return GNUNET_OK on success
340  */
341 int
342 GNUNET_DISK_file_get_identifiers (const char *filename, uint64_t * dev,
343                                   uint64_t * ino);
344
345
346 /**
347  * Create an (empty) temporary file on disk.  If the given name is not
348  * an absolute path, the current 'TMPDIR' will be prepended.  In any case,
349  * 6 random characters will be appended to the name to create a unique
350  * filename.
351  *
352  * @param t component to use for the name;
353  *        does NOT contain "XXXXXX" or "/tmp/".
354  * @return NULL on error, otherwise name of fresh
355  *         file on disk in directory for temporary files
356  */
357 char *
358 GNUNET_DISK_mktemp (const char *t);
359
360
361 /**
362  * Open a file.  Note that the access permissions will only be
363  * used if a new file is created and if the underlying operating
364  * system supports the given permissions.
365  *
366  * @param fn file name to be opened
367  * @param flags opening flags, a combination of GNUNET_DISK_OPEN_xxx bit flags
368  * @param perm permissions for the newly created file, use
369  *             GNUNET_DISK_PERM_NONE if a file could not be created by this
370  *             call (because of flags)
371  * @return IO handle on success, NULL on error
372  */
373 struct GNUNET_DISK_FileHandle *
374 GNUNET_DISK_file_open (const char *fn, enum GNUNET_DISK_OpenFlags flags,
375                        enum GNUNET_DISK_AccessPermissions perm);
376
377
378 /**
379  * Get the size of an open file.
380  *
381  * @param fh open file handle
382  * @param size where to write size of the file
383  * @return GNUNET_OK on success, GNUNET_SYSERR on error
384  */
385 int
386 GNUNET_DISK_file_handle_size (struct GNUNET_DISK_FileHandle *fh,
387                               OFF_T *size);
388
389
390 /**
391  * Creates an interprocess channel
392  * @param blocking creates an asynchronous pipe if set to GNUNET_NO
393  * @param inherit_read 1 to make read handle inheritable, 0 otherwise (NT only)
394  * @param inherit_write 1 to make write handle inheritable, 0 otherwise (NT only)
395  * @return handle to the new pipe, NULL on error
396  */
397 struct GNUNET_DISK_PipeHandle *
398 GNUNET_DISK_pipe (int blocking, int inherit_read, int inherit_write);
399
400
401 /**
402  * Closes an interprocess channel
403  * @param p pipe
404  * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
405  */
406 int
407 GNUNET_DISK_pipe_close (struct GNUNET_DISK_PipeHandle *p);
408
409 /**
410  * Closes one half of an interprocess channel
411  *
412  * @param p pipe to close end of
413  * @param end which end of the pipe to close
414  * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
415  */
416 int
417 GNUNET_DISK_pipe_close_end (struct GNUNET_DISK_PipeHandle *p,
418                             enum GNUNET_DISK_PipeEnd end);
419
420 /**
421  * Close an open file.
422  *
423  * @param h file handle
424  * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
425  */
426 int
427 GNUNET_DISK_file_close (struct GNUNET_DISK_FileHandle *h);
428
429
430 /**
431  * Get the handle to a particular pipe end
432  *
433  * @param p pipe
434  * @param n end to access
435  * @return handle for the respective end
436  */
437 const struct GNUNET_DISK_FileHandle *
438 GNUNET_DISK_pipe_handle (const struct GNUNET_DISK_PipeHandle *p,
439                          enum GNUNET_DISK_PipeEnd n);
440
441 /**
442  * Read the contents of a binary file into a buffer.
443  * @param h handle to an open file
444  * @param result the buffer to write the result to
445  * @param len the maximum number of bytes to read
446  * @return the number of bytes read on success, GNUNET_SYSERR on failure
447  */
448 ssize_t
449 GNUNET_DISK_file_read (const struct GNUNET_DISK_FileHandle *h, void *result,
450                        size_t len);
451
452
453 /**
454  * Read the contents of a binary file into a buffer.
455  *
456  * @param fn file name
457  * @param result the buffer to write the result to
458  * @param len the maximum number of bytes to read
459  * @return number of bytes read, GNUNET_SYSERR on failure
460  */
461 ssize_t
462 GNUNET_DISK_fn_read (const char *fn, void *result, size_t len);
463
464
465 /**
466  * Write a buffer to a file.
467  *
468  * @param h handle to open file
469  * @param buffer the data to write
470  * @param n number of bytes to write
471  * @return number of bytes written on success, GNUNET_SYSERR on error
472  */
473 ssize_t
474 GNUNET_DISK_file_write (const struct GNUNET_DISK_FileHandle *h,
475                         const void *buffer, size_t n);
476
477
478 /**
479  * Write a buffer to a file.  If the file is longer than
480  * the given buffer size, it will be truncated.
481  *
482  * @param fn file name
483  * @param buffer the data to write
484  * @param n number of bytes to write
485  * @param mode file permissions
486  * @return number of bytes written on success, GNUNET_SYSERR on error
487  */
488 ssize_t
489 GNUNET_DISK_fn_write (const char *fn, const void *buffer, size_t n,
490                       enum GNUNET_DISK_AccessPermissions mode);
491
492
493 /**
494  * Copy a file.
495  *
496  * @param src file to copy
497  * @param dst destination file name
498  * @return GNUNET_OK on success, GNUNET_SYSERR on error
499  */
500 int
501 GNUNET_DISK_file_copy (const char *src, const char *dst);
502
503
504 /**
505  * Scan a directory for files.
506  *
507  * @param dirName the name of the directory
508  * @param callback the method to call for each file
509  * @param callback_cls closure for callback
510  * @return the number of files found, -1 on error
511  */
512 int
513 GNUNET_DISK_directory_scan (const char *dirName,
514                             GNUNET_FileNameCallback callback,
515                             void *callback_cls);
516
517
518 /**
519  * Opaque handle used for iterating over a directory.
520  */
521 struct GNUNET_DISK_DirectoryIterator;
522
523
524 /**
525  * Function called to iterate over a directory.
526  *
527  * @param cls closure
528  * @param di argument to pass to "GNUNET_DISK_directory_iterator_next" to
529  *           get called on the next entry (or finish cleanly);
530  *           NULL on error (will be the last call in that case)
531  * @param filename complete filename (absolute path)
532  * @param dirname directory name (absolute path)
533  */
534 typedef void (*GNUNET_DISK_DirectoryIteratorCallback) (void *cls,
535                                                        struct
536                                                        GNUNET_DISK_DirectoryIterator
537                                                        * di,
538                                                        const char *filename,
539                                                        const char *dirname);
540
541
542 /**
543  * This function must be called during the DiskIteratorCallback
544  * (exactly once) to schedule the task to process the next
545  * filename in the directory (if there is one).
546  *
547  * @param iter opaque handle for the iterator
548  * @param can set to GNUNET_YES to terminate the iteration early
549  * @return GNUNET_YES if iteration will continue,
550  *         GNUNET_NO if this was the last entry (and iteration is complete),
551  *         GNUNET_SYSERR if "can" was YES
552  */
553 int
554 GNUNET_DISK_directory_iterator_next (struct GNUNET_DISK_DirectoryIterator *iter,
555                                      int can);
556
557
558 /**
559  * Scan a directory for files using the scheduler to run a task for
560  * each entry.  The name of the directory must be expanded first (!).
561  * If a scheduler does not need to be used, GNUNET_DISK_directory_scan
562  * may provide a simpler API.
563  *
564  * @param prio priority to use
565  * @param dirName the name of the directory
566  * @param callback the method to call for each file
567  * @param callback_cls closure for callback
568  * @return GNUNET_YES if directory is not empty and @callback
569  *         will be called later, GNUNET_NO otherwise, GNUNET_SYSERR on error.
570  */
571 int
572 GNUNET_DISK_directory_iterator_start (enum GNUNET_SCHEDULER_Priority prio,
573                                       const char *dirName,
574                                       GNUNET_DISK_DirectoryIteratorCallback
575                                       callback, void *callback_cls);
576
577
578 /**
579  * Create the directory structure for storing
580  * a file.
581  *
582  * @param filename name of a file in the directory
583  * @returns GNUNET_OK on success, GNUNET_SYSERR on failure,
584  *          GNUNET_NO if directory exists but is not writeable
585  */
586 int
587 GNUNET_DISK_directory_create_for_file (const char *filename);
588
589
590 /**
591  * Test if "fil" is a directory that can be accessed.
592  * Will not print an error message if the directory
593  * does not exist.  Will log errors if GNUNET_SYSERR is
594  * returned.
595  *
596  * @param fil filename to test
597  * @return GNUNET_YES if yes, GNUNET_NO if does not exist, GNUNET_SYSERR
598  *   on any error and if exists but not directory
599  */
600 int
601 GNUNET_DISK_directory_test (const char *fil);
602
603
604 /**
605  * Remove all files in a directory (rm -rf). Call with
606  * caution.
607  *
608  * @param fileName the file to remove
609  * @return GNUNET_OK on success, GNUNET_SYSERR on error
610  */
611 int
612 GNUNET_DISK_directory_remove (const char *fileName);
613
614
615 /**
616  * Implementation of "mkdir -p"
617  *
618  * @param dir the directory to create
619  * @returns GNUNET_SYSERR on failure, GNUNET_OK otherwise
620  */
621 int
622 GNUNET_DISK_directory_create (const char *dir);
623
624
625 /**
626  * Lock a part of a file.
627  *
628  * @param fh file handle
629  * @param lockStart absolute position from where to lock
630  * @param lockEnd absolute position until where to lock
631  * @param excl GNUNET_YES for an exclusive lock
632  * @return GNUNET_OK on success, GNUNET_SYSERR on error
633  */
634 int
635 GNUNET_DISK_file_lock (struct GNUNET_DISK_FileHandle *fh, OFF_T lockStart,
636                        OFF_T lockEnd, int excl);
637
638
639 /**
640  * Unlock a part of a file
641  * @param fh file handle
642  * @param unlockStart absolute position from where to unlock
643  * @param unlockEnd absolute position until where to unlock
644  * @return GNUNET_OK on success, GNUNET_SYSERR on error
645  */
646 int
647 GNUNET_DISK_file_unlock (struct GNUNET_DISK_FileHandle *fh, OFF_T unlockStart,
648                          OFF_T unlockEnd);
649
650
651 /**
652  * @brief Removes special characters as ':' from a filename.
653  * @param fn the filename to canonicalize
654  */
655 void
656 GNUNET_DISK_filename_canonicalize (char *fn);
657
658
659 /**
660  * @brief Change owner of a file
661  * @param filename file to change
662  * @param user new owner of the file
663  * @return GNUNET_OK on success, GNUNET_SYSERR on failure
664  */
665 int
666 GNUNET_DISK_file_change_owner (const char *filename, const char *user);
667
668
669 /**
670  * Construct full path to a file inside of the private
671  * directory used by GNUnet.  Also creates the corresponding
672  * directory.  If the resulting name is supposed to be
673  * a directory, end the last argument in '/' (or pass
674  * DIR_SEPARATOR_STR as the last argument before NULL).
675  *
676  * @param cfg configuration to use
677  * @param serviceName name of the service asking
678  * @param ... is NULL-terminated list of
679  *                path components to append to the
680  *                private directory name.
681  * @return the constructed filename
682  */
683 char *
684 GNUNET_DISK_get_home_filename (const struct GNUNET_CONFIGURATION_Handle *cfg,
685                                const char *serviceName, ...);
686
687
688 /**
689  * Opaque handle for a memory-mapping operation.
690  */
691 struct GNUNET_DISK_MapHandle;
692
693 /**
694  * Map a file into memory
695  * @param h open file handle
696  * @param m handle to the new mapping (will be set)
697  * @param access access specification, GNUNET_DISK_MAP_TYPE_xxx
698  * @param len size of the mapping
699  * @return pointer to the mapped memory region, NULL on failure
700  */
701 void *
702 GNUNET_DISK_file_map (const struct GNUNET_DISK_FileHandle *h,
703                       struct GNUNET_DISK_MapHandle **m,
704                       enum GNUNET_DISK_MapType access, size_t len);
705
706 /**
707  * Unmap a file
708  *
709  * @param h mapping handle
710  * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
711  */
712 int
713 GNUNET_DISK_file_unmap (struct GNUNET_DISK_MapHandle *h);
714
715 /**
716  * Write file changes to disk
717  * @param h handle to an open file
718  * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
719  */
720 int
721 GNUNET_DISK_file_sync (const struct GNUNET_DISK_FileHandle *h);
722
723 /**
724  * Creates a named pipe/FIFO and opens it
725  * @param fn pointer to the name of the named pipe or to NULL
726  * @param flags open flags
727  * @param perm access permissions
728  * @return pipe handle on success, NULL on error
729  */
730 struct GNUNET_DISK_FileHandle *
731 GNUNET_DISK_npipe_create (char **fn, enum GNUNET_DISK_OpenFlags flags,
732                           enum GNUNET_DISK_AccessPermissions perm);
733
734 /**
735  * Opens already existing named pipe/FIFO
736  *
737  * @param fn name of an existing named pipe
738  * @param flags open flags
739  * @param perm access permissions
740  * @return pipe handle on success, NULL on error
741  */
742 struct GNUNET_DISK_FileHandle *
743 GNUNET_DISK_npipe_open (const char *fn, enum GNUNET_DISK_OpenFlags flags,
744                         enum GNUNET_DISK_AccessPermissions perm);
745
746 /**
747  * Closes a named pipe/FIFO
748  * @param pipe named pipe
749  * @return GNUNET_OK on success, GNUNET_SYSERR otherwise
750  */
751 int
752 GNUNET_DISK_npipe_close (struct GNUNET_DISK_FileHandle *pipe);
753
754 #if 0                           /* keep Emacsens' auto-indent happy */
755 {
756 #endif
757 #ifdef __cplusplus
758 }
759 #endif
760
761
762 /* ifndef GNUNET_DISK_LIB_H */
763 #endif
764 /* end of gnunet_disk_lib.h */