aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_disk_lib.h
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2013-10-06 09:35:14 +0000
committerChristian Grothoff <christian@grothoff.org>2013-10-06 09:35:14 +0000
commit99ba3c2b1294b890671d0d7d6e4319be70bee5a0 (patch)
tree2e9b1339869d5f115b80246b63af6c0604023e75 /src/include/gnunet_disk_lib.h
parentaee28f4afd42710aba0c37d8ec86572aef092044 (diff)
downloadgnunet-99ba3c2b1294b890671d0d7d6e4319be70bee5a0.tar.gz
gnunet-99ba3c2b1294b890671d0d7d6e4319be70bee5a0.zip
-doxygen, coding conventions
Diffstat (limited to 'src/include/gnunet_disk_lib.h')
-rw-r--r--src/include/gnunet_disk_lib.h107
1 files changed, 56 insertions, 51 deletions
diff --git a/src/include/gnunet_disk_lib.h b/src/include/gnunet_disk_lib.h
index 022cfc2af..a800010f8 100644
--- a/src/include/gnunet_disk_lib.h
+++ b/src/include/gnunet_disk_lib.h
@@ -387,7 +387,7 @@ GNUNET_DISK_mkdtemp (const char *t);
387 * @param fn file name to be opened 387 * @param fn file name to be opened
388 * @param flags opening flags, a combination of GNUNET_DISK_OPEN_xxx bit flags 388 * @param flags opening flags, a combination of GNUNET_DISK_OPEN_xxx bit flags
389 * @param perm permissions for the newly created file, use 389 * @param perm permissions for the newly created file, use
390 * GNUNET_DISK_PERM_NONE if a file could not be created by this 390 * #GNUNET_DISK_PERM_NONE if a file could not be created by this
391 * call (because of flags) 391 * call (because of flags)
392 * @return IO handle on success, NULL on error 392 * @return IO handle on success, NULL on error
393 */ 393 */
@@ -401,7 +401,7 @@ GNUNET_DISK_file_open (const char *fn, enum GNUNET_DISK_OpenFlags flags,
401 * 401 *
402 * @param fh open file handle 402 * @param fh open file handle
403 * @param size where to write size of the file 403 * @param size where to write size of the file
404 * @return GNUNET_OK on success, GNUNET_SYSERR on error 404 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
405 */ 405 */
406int 406int
407GNUNET_DISK_file_handle_size (struct GNUNET_DISK_FileHandle *fh, 407GNUNET_DISK_file_handle_size (struct GNUNET_DISK_FileHandle *fh,
@@ -411,8 +411,8 @@ GNUNET_DISK_file_handle_size (struct GNUNET_DISK_FileHandle *fh,
411/** 411/**
412 * Creates an interprocess channel 412 * Creates an interprocess channel
413 * 413 *
414 * @param blocking_read creates an asynchronous pipe for reading if set to GNUNET_NO 414 * @param blocking_read creates an asynchronous pipe for reading if set to #GNUNET_NO
415 * @param blocking_write creates an asynchronous pipe for writing if set to GNUNET_NO 415 * @param blocking_write creates an asynchronous pipe for writing if set to #GNUNET_NO
416 * @param inherit_read 1 to make read handle inheritable, 0 otherwise (NT only) 416 * @param inherit_read 1 to make read handle inheritable, 0 otherwise (NT only)
417 * @param inherit_write 1 to make write handle inheritable, 0 otherwise (NT only) 417 * @param inherit_write 1 to make write handle inheritable, 0 otherwise (NT only)
418 * @return handle to the new pipe, NULL on error 418 * @return handle to the new pipe, NULL on error
@@ -425,8 +425,8 @@ GNUNET_DISK_pipe (int blocking_read, int blocking_write, int inherit_read, int i
425 * Creates a pipe object from a couple of file descriptors. 425 * Creates a pipe object from a couple of file descriptors.
426 * Useful for wrapping existing pipe FDs. 426 * Useful for wrapping existing pipe FDs.
427 * 427 *
428 * @param blocking_read creates an asynchronous pipe for reading if set to GNUNET_NO 428 * @param blocking_read creates an asynchronous pipe for reading if set to #GNUNET_NO
429 * @param blocking_write creates an asynchronous pipe for writing if set to GNUNET_NO 429 * @param blocking_write creates an asynchronous pipe for writing if set to #GNUNET_NO
430 * @param fd an array of two fd values. One of them may be -1 for read-only or write-only pipes 430 * @param fd an array of two fd values. One of them may be -1 for read-only or write-only pipes
431 * 431 *
432 * @return handle to the new pipe, NULL on error 432 * @return handle to the new pipe, NULL on error
@@ -438,7 +438,7 @@ GNUNET_DISK_pipe_from_fd (int blocking_read, int blocking_write, int fd[2]);
438/** 438/**
439 * Closes an interprocess channel 439 * Closes an interprocess channel
440 * @param p pipe 440 * @param p pipe
441 * @return GNUNET_OK on success, GNUNET_SYSERR otherwise 441 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
442 */ 442 */
443int 443int
444GNUNET_DISK_pipe_close (struct GNUNET_DISK_PipeHandle *p); 444GNUNET_DISK_pipe_close (struct GNUNET_DISK_PipeHandle *p);
@@ -449,12 +449,13 @@ GNUNET_DISK_pipe_close (struct GNUNET_DISK_PipeHandle *p);
449 * 449 *
450 * @param p pipe to close end of 450 * @param p pipe to close end of
451 * @param end which end of the pipe to close 451 * @param end which end of the pipe to close
452 * @return GNUNET_OK on success, GNUNET_SYSERR otherwise 452 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
453 */ 453 */
454int 454int
455GNUNET_DISK_pipe_close_end (struct GNUNET_DISK_PipeHandle *p, 455GNUNET_DISK_pipe_close_end (struct GNUNET_DISK_PipeHandle *p,
456 enum GNUNET_DISK_PipeEnd end); 456 enum GNUNET_DISK_PipeEnd end);
457 457
458
458/** 459/**
459 * Detaches one of the ends from the pipe. 460 * Detaches one of the ends from the pipe.
460 * Detached end is a fully-functional FileHandle, it will 461 * Detached end is a fully-functional FileHandle, it will
@@ -505,6 +506,7 @@ struct GNUNET_DISK_FileHandle *
505GNUNET_DISK_get_handle_from_w32_handle (HANDLE osfh); 506GNUNET_DISK_get_handle_from_w32_handle (HANDLE osfh);
506#endif 507#endif
507 508
509
508/** 510/**
509 * Get a handle from a native integer FD. 511 * Get a handle from a native integer FD.
510 * 512 *
@@ -514,6 +516,7 @@ GNUNET_DISK_get_handle_from_w32_handle (HANDLE osfh);
514struct GNUNET_DISK_FileHandle * 516struct GNUNET_DISK_FileHandle *
515GNUNET_DISK_get_handle_from_int_fd (int fno); 517GNUNET_DISK_get_handle_from_int_fd (int fno);
516 518
519
517/** 520/**
518 * Get a handle from a native FD. 521 * Get a handle from a native FD.
519 * 522 *
@@ -529,7 +532,7 @@ GNUNET_DISK_get_handle_from_native (FILE *fd);
529 * @param h handle to an open file 532 * @param h handle to an open file
530 * @param result the buffer to write the result to 533 * @param result the buffer to write the result to
531 * @param len the maximum number of bytes to read 534 * @param len the maximum number of bytes to read
532 * @return the number of bytes read on success, GNUNET_SYSERR on failure 535 * @return the number of bytes read on success, #GNUNET_SYSERR on failure
533 */ 536 */
534ssize_t 537ssize_t
535GNUNET_DISK_file_read (const struct GNUNET_DISK_FileHandle *h, void *result, 538GNUNET_DISK_file_read (const struct GNUNET_DISK_FileHandle *h, void *result,
@@ -544,11 +547,12 @@ GNUNET_DISK_file_read (const struct GNUNET_DISK_FileHandle *h, void *result,
544 * @param h handle to an open file 547 * @param h handle to an open file
545 * @param result the buffer to write the result to 548 * @param result the buffer to write the result to
546 * @param len the maximum number of bytes to read 549 * @param len the maximum number of bytes to read
547 * @return the number of bytes read on success, GNUNET_SYSERR on failure 550 * @return the number of bytes read on success, #GNUNET_SYSERR on failure
548 */ 551 */
549ssize_t 552ssize_t
550GNUNET_DISK_file_read_non_blocking (const struct GNUNET_DISK_FileHandle * h, 553GNUNET_DISK_file_read_non_blocking (const struct GNUNET_DISK_FileHandle * h,
551 void *result, size_t len); 554 void *result,
555 size_t len);
552 556
553 557
554/** 558/**
@@ -557,10 +561,12 @@ GNUNET_DISK_file_read_non_blocking (const struct GNUNET_DISK_FileHandle * h,
557 * @param fn file name 561 * @param fn file name
558 * @param result the buffer to write the result to 562 * @param result the buffer to write the result to
559 * @param len the maximum number of bytes to read 563 * @param len the maximum number of bytes to read
560 * @return number of bytes read, GNUNET_SYSERR on failure 564 * @return number of bytes read, #GNUNET_SYSERR on failure
561 */ 565 */
562ssize_t 566ssize_t
563GNUNET_DISK_fn_read (const char *fn, void *result, size_t len); 567GNUNET_DISK_fn_read (const char *fn,
568 void *result,
569 size_t len);
564 570
565 571
566/** 572/**
@@ -569,7 +575,7 @@ GNUNET_DISK_fn_read (const char *fn, void *result, size_t len);
569 * @param h handle to open file 575 * @param h handle to open file
570 * @param buffer the data to write 576 * @param buffer the data to write
571 * @param n number of bytes to write 577 * @param n number of bytes to write
572 * @return number of bytes written on success, GNUNET_SYSERR on error 578 * @return number of bytes written on success, #GNUNET_SYSERR on error
573 */ 579 */
574ssize_t 580ssize_t
575GNUNET_DISK_file_write (const struct GNUNET_DISK_FileHandle *h, 581GNUNET_DISK_file_write (const struct GNUNET_DISK_FileHandle *h,
@@ -581,7 +587,7 @@ GNUNET_DISK_file_write (const struct GNUNET_DISK_FileHandle *h,
581 * @param h handle to open file 587 * @param h handle to open file
582 * @param buffer the data to write 588 * @param buffer the data to write
583 * @param n number of bytes to write 589 * @param n number of bytes to write
584 * @return number of bytes written on success, GNUNET_SYSERR on error 590 * @return number of bytes written on success, #GNUNET_SYSERR on error
585 */ 591 */
586ssize_t 592ssize_t
587GNUNET_DISK_file_write_blocking (const struct GNUNET_DISK_FileHandle * h, 593GNUNET_DISK_file_write_blocking (const struct GNUNET_DISK_FileHandle * h,
@@ -597,7 +603,7 @@ GNUNET_DISK_file_write_blocking (const struct GNUNET_DISK_FileHandle * h,
597 * @param buffer the data to write 603 * @param buffer the data to write
598 * @param n number of bytes to write 604 * @param n number of bytes to write
599 * @param mode file permissions 605 * @param mode file permissions
600 * @return number of bytes written on success, GNUNET_SYSERR on error 606 * @return number of bytes written on success, #GNUNET_SYSERR on error
601 */ 607 */
602ssize_t 608ssize_t
603GNUNET_DISK_fn_write (const char *fn, const void *buffer, size_t n, 609GNUNET_DISK_fn_write (const char *fn, const void *buffer, size_t n,
@@ -609,7 +615,7 @@ GNUNET_DISK_fn_write (const char *fn, const void *buffer, size_t n,
609 * 615 *
610 * @param src file to copy 616 * @param src file to copy
611 * @param dst destination file name 617 * @param dst destination file name
612 * @return GNUNET_OK on success, GNUNET_SYSERR on error 618 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
613 */ 619 */
614int 620int
615GNUNET_DISK_file_copy (const char *src, const char *dst); 621GNUNET_DISK_file_copy (const char *src, const char *dst);
@@ -618,13 +624,13 @@ GNUNET_DISK_file_copy (const char *src, const char *dst);
618/** 624/**
619 * Scan a directory for files. 625 * Scan a directory for files.
620 * 626 *
621 * @param dirName the name of the directory 627 * @param dir_name the name of the directory
622 * @param callback the method to call for each file 628 * @param callback the method to call for each file
623 * @param callback_cls closure for callback 629 * @param callback_cls closure for @a callback
624 * @return the number of files found, -1 on error 630 * @return the number of files found, -1 on error
625 */ 631 */
626int 632int
627GNUNET_DISK_directory_scan (const char *dirName, 633GNUNET_DISK_directory_scan (const char *dir_name,
628 GNUNET_FileNameCallback callback, 634 GNUNET_FileNameCallback callback,
629 void *callback_cls); 635 void *callback_cls);
630 636
@@ -639,16 +645,14 @@ struct GNUNET_DISK_DirectoryIterator;
639 * Function called to iterate over a directory. 645 * Function called to iterate over a directory.
640 * 646 *
641 * @param cls closure 647 * @param cls closure
642 * @param di argument to pass to "GNUNET_DISK_directory_iterator_next" to 648 * @param di argument to pass to #GNUNET_DISK_directory_iterator_next to
643 * get called on the next entry (or finish cleanly); 649 * get called on the next entry (or finish cleanly);
644 * NULL on error (will be the last call in that case) 650 * NULL on error (will be the last call in that case)
645 * @param filename complete filename (absolute path) 651 * @param filename complete filename (absolute path)
646 * @param dirname directory name (absolute path) 652 * @param dirname directory name (absolute path)
647 */ 653 */
648typedef void (*GNUNET_DISK_DirectoryIteratorCallback) (void *cls, 654typedef void (*GNUNET_DISK_DirectoryIteratorCallback) (void *cls,
649 struct 655 struct GNUNET_DISK_DirectoryIterator *di,
650 GNUNET_DISK_DirectoryIterator
651 * di,
652 const char *filename, 656 const char *filename,
653 const char *dirname); 657 const char *dirname);
654 658
@@ -659,10 +663,10 @@ typedef void (*GNUNET_DISK_DirectoryIteratorCallback) (void *cls,
659 * filename in the directory (if there is one). 663 * filename in the directory (if there is one).
660 * 664 *
661 * @param iter opaque handle for the iterator 665 * @param iter opaque handle for the iterator
662 * @param can set to GNUNET_YES to terminate the iteration early 666 * @param can set to #GNUNET_YES to terminate the iteration early
663 * @return GNUNET_YES if iteration will continue, 667 * @return #GNUNET_YES if iteration will continue,
664 * GNUNET_NO if this was the last entry (and iteration is complete), 668 * #GNUNET_NO if this was the last entry (and iteration is complete),
665 * GNUNET_SYSERR if "can" was YES 669 * #GNUNET_SYSERR if @a can was #GNUNET_YES
666 */ 670 */
667int 671int
668GNUNET_DISK_directory_iterator_next (struct GNUNET_DISK_DirectoryIterator *iter, 672GNUNET_DISK_directory_iterator_next (struct GNUNET_DISK_DirectoryIterator *iter,
@@ -676,15 +680,15 @@ GNUNET_DISK_directory_iterator_next (struct GNUNET_DISK_DirectoryIterator *iter,
676 * may provide a simpler API. 680 * may provide a simpler API.
677 * 681 *
678 * @param prio priority to use 682 * @param prio priority to use
679 * @param dirName the name of the directory 683 * @param dir_name the name of the directory
680 * @param callback the method to call for each file 684 * @param callback the method to call for each file
681 * @param callback_cls closure for callback 685 * @param callback_cls closure for @a callback
682 * @return GNUNET_YES if directory is not empty and 'callback' 686 * @return #GNUNET_YES if directory is not empty and @a callback
683 * will be called later, GNUNET_NO otherwise, GNUNET_SYSERR on error. 687 * will be called later, #GNUNET_NO otherwise, #GNUNET_SYSERR on error.
684 */ 688 */
685int 689int
686GNUNET_DISK_directory_iterator_start (enum GNUNET_SCHEDULER_Priority prio, 690GNUNET_DISK_directory_iterator_start (enum GNUNET_SCHEDULER_Priority prio,
687 const char *dirName, 691 const char *dir_name,
688 GNUNET_DISK_DirectoryIteratorCallback 692 GNUNET_DISK_DirectoryIteratorCallback
689 callback, void *callback_cls); 693 callback, void *callback_cls);
690 694
@@ -694,24 +698,24 @@ GNUNET_DISK_directory_iterator_start (enum GNUNET_SCHEDULER_Priority prio,
694 * a file. 698 * a file.
695 * 699 *
696 * @param filename name of a file in the directory 700 * @param filename name of a file in the directory
697 * @returns GNUNET_OK on success, GNUNET_SYSERR on failure, 701 * @returns #GNUNET_OK on success, #GNUNET_SYSERR on failure,
698 * GNUNET_NO if directory exists but is not writeable 702 * #GNUNET_NO if directory exists but is not writeable
699 */ 703 */
700int 704int
701GNUNET_DISK_directory_create_for_file (const char *filename); 705GNUNET_DISK_directory_create_for_file (const char *filename);
702 706
703 707
704/** 708/**
705 * Test if "fil" is a directory and listable. Optionally, also check if the 709 * Test if @a fil is a directory and listable. Optionally, also check if the
706 * directory is readable. Will not print an error message if the directory does 710 * directory is readable. Will not print an error message if the directory does
707 * not exist. Will log errors if GNUNET_SYSERR is returned (i.e., a file exists 711 * not exist. Will log errors if #GNUNET_SYSERR is returned (i.e., a file exists
708 * with the same name). 712 * with the same name).
709 * 713 *
710 * @param fil filename to test 714 * @param fil filename to test
711 * @param is_readable GNUNET_YES to additionally check if "fil" is readable; 715 * @param is_readable #GNUNET_YES to additionally check if @a fil is readable;
712 * GNUNET_NO to disable this check 716 * #GNUNET_NO to disable this check
713 * @return GNUNET_YES if yes, GNUNET_NO if not; GNUNET_SYSERR if it 717 * @return #GNUNET_YES if yes, #GNUNET_NO if not; #GNUNET_SYSERR if it
714 * does not exist or stat'ed 718 * does not exist or `stat`ed
715 */ 719 */
716int 720int
717GNUNET_DISK_directory_test (const char *fil, int is_readable); 721GNUNET_DISK_directory_test (const char *fil, int is_readable);
@@ -742,27 +746,28 @@ GNUNET_DISK_directory_create (const char *dir);
742 * Lock a part of a file. 746 * Lock a part of a file.
743 * 747 *
744 * @param fh file handle 748 * @param fh file handle
745 * @param lockStart absolute position from where to lock 749 * @param lock_start absolute position from where to lock
746 * @param lockEnd absolute position until where to lock 750 * @param lock_end absolute position until where to lock
747 * @param excl #GNUNET_YES for an exclusive lock 751 * @param excl #GNUNET_YES for an exclusive lock
748 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error 752 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
749 */ 753 */
750int 754int
751GNUNET_DISK_file_lock (struct GNUNET_DISK_FileHandle *fh, OFF_T lockStart, 755GNUNET_DISK_file_lock (struct GNUNET_DISK_FileHandle *fh,
752 OFF_T lockEnd, int excl); 756 OFF_T lock_start,
757 OFF_T lock_end, int excl);
753 758
754 759
755/** 760/**
756 * Unlock a part of a file. 761 * Unlock a part of a file.
757 * 762 *
758 * @param fh file handle 763 * @param fh file handle
759 * @param unlockStart absolute position from where to unlock 764 * @param unlock_start absolute position from where to unlock
760 * @param unlockEnd absolute position until where to unlock 765 * @param unlock_end absolute position until where to unlock
761 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error 766 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
762 */ 767 */
763int 768int
764GNUNET_DISK_file_unlock (struct GNUNET_DISK_FileHandle *fh, OFF_T unlockStart, 769GNUNET_DISK_file_unlock (struct GNUNET_DISK_FileHandle *fh, OFF_T unlock_start,
765 OFF_T unlockEnd); 770 OFF_T unlock_end);
766 771
767 772
768/** 773/**
@@ -791,7 +796,7 @@ GNUNET_DISK_file_change_owner (const char *filename, const char *user);
791 * DIR_SEPARATOR_STR as the last argument before NULL). 796 * DIR_SEPARATOR_STR as the last argument before NULL).
792 * 797 *
793 * @param cfg configuration to use 798 * @param cfg configuration to use
794 * @param serviceName name of the service asking 799 * @param service_name name of the service asking
795 * @param ... is NULL-terminated list of 800 * @param ... is NULL-terminated list of
796 * path components to append to the 801 * path components to append to the
797 * private directory name. 802 * private directory name.
@@ -799,7 +804,7 @@ GNUNET_DISK_file_change_owner (const char *filename, const char *user);
799 */ 804 */
800char * 805char *
801GNUNET_DISK_get_home_filename (const struct GNUNET_CONFIGURATION_Handle *cfg, 806GNUNET_DISK_get_home_filename (const struct GNUNET_CONFIGURATION_Handle *cfg,
802 const char *serviceName, ...); 807 const char *service_name, ...);
803 808
804 809
805/** 810/**