diff options
author | Christian Grothoff <christian@grothoff.org> | 2013-10-06 09:35:14 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2013-10-06 09:35:14 +0000 |
commit | 99ba3c2b1294b890671d0d7d6e4319be70bee5a0 (patch) | |
tree | 2e9b1339869d5f115b80246b63af6c0604023e75 /src/include/gnunet_disk_lib.h | |
parent | aee28f4afd42710aba0c37d8ec86572aef092044 (diff) | |
download | gnunet-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.h | 107 |
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 | */ |
406 | int | 406 | int |
407 | GNUNET_DISK_file_handle_size (struct GNUNET_DISK_FileHandle *fh, | 407 | GNUNET_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 | */ |
443 | int | 443 | int |
444 | GNUNET_DISK_pipe_close (struct GNUNET_DISK_PipeHandle *p); | 444 | GNUNET_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 | */ |
454 | int | 454 | int |
455 | GNUNET_DISK_pipe_close_end (struct GNUNET_DISK_PipeHandle *p, | 455 | GNUNET_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 * | |||
505 | GNUNET_DISK_get_handle_from_w32_handle (HANDLE osfh); | 506 | GNUNET_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); | |||
514 | struct GNUNET_DISK_FileHandle * | 516 | struct GNUNET_DISK_FileHandle * |
515 | GNUNET_DISK_get_handle_from_int_fd (int fno); | 517 | GNUNET_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 | */ |
534 | ssize_t | 537 | ssize_t |
535 | GNUNET_DISK_file_read (const struct GNUNET_DISK_FileHandle *h, void *result, | 538 | GNUNET_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 | */ |
549 | ssize_t | 552 | ssize_t |
550 | GNUNET_DISK_file_read_non_blocking (const struct GNUNET_DISK_FileHandle * h, | 553 | GNUNET_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 | */ |
562 | ssize_t | 566 | ssize_t |
563 | GNUNET_DISK_fn_read (const char *fn, void *result, size_t len); | 567 | GNUNET_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 | */ |
574 | ssize_t | 580 | ssize_t |
575 | GNUNET_DISK_file_write (const struct GNUNET_DISK_FileHandle *h, | 581 | GNUNET_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 | */ |
586 | ssize_t | 592 | ssize_t |
587 | GNUNET_DISK_file_write_blocking (const struct GNUNET_DISK_FileHandle * h, | 593 | GNUNET_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 | */ |
602 | ssize_t | 608 | ssize_t |
603 | GNUNET_DISK_fn_write (const char *fn, const void *buffer, size_t n, | 609 | GNUNET_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 | */ |
614 | int | 620 | int |
615 | GNUNET_DISK_file_copy (const char *src, const char *dst); | 621 | GNUNET_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 | */ |
626 | int | 632 | int |
627 | GNUNET_DISK_directory_scan (const char *dirName, | 633 | GNUNET_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 | */ |
648 | typedef void (*GNUNET_DISK_DirectoryIteratorCallback) (void *cls, | 654 | typedef 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 | */ |
667 | int | 671 | int |
668 | GNUNET_DISK_directory_iterator_next (struct GNUNET_DISK_DirectoryIterator *iter, | 672 | GNUNET_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 | */ |
685 | int | 689 | int |
686 | GNUNET_DISK_directory_iterator_start (enum GNUNET_SCHEDULER_Priority prio, | 690 | GNUNET_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 | */ |
700 | int | 704 | int |
701 | GNUNET_DISK_directory_create_for_file (const char *filename); | 705 | GNUNET_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 | */ |
716 | int | 720 | int |
717 | GNUNET_DISK_directory_test (const char *fil, int is_readable); | 721 | GNUNET_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 | */ |
750 | int | 754 | int |
751 | GNUNET_DISK_file_lock (struct GNUNET_DISK_FileHandle *fh, OFF_T lockStart, | 755 | GNUNET_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 | */ |
763 | int | 768 | int |
764 | GNUNET_DISK_file_unlock (struct GNUNET_DISK_FileHandle *fh, OFF_T unlockStart, | 769 | GNUNET_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 | */ |
800 | char * | 805 | char * |
801 | GNUNET_DISK_get_home_filename (const struct GNUNET_CONFIGURATION_Handle *cfg, | 806 | GNUNET_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 | /** |