diff options
author | Christian Grothoff <christian@grothoff.org> | 2013-08-29 22:31:07 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2013-08-29 22:31:07 +0000 |
commit | 9fc4769028236bb2c83b956e1afcba3e5257f936 (patch) | |
tree | df8cdcd654a91558ee9a057393629c6bd51c38ab /src/util/network.c | |
parent | fcff7aaef106e5bd78e340ba9540667614d5a202 (diff) | |
download | gnunet-9fc4769028236bb2c83b956e1afcba3e5257f936.tar.gz gnunet-9fc4769028236bb2c83b956e1afcba3e5257f936.zip |
-fix u/clarify/improve util/network code doxygen documentation
Diffstat (limited to 'src/util/network.c')
-rw-r--r-- | src/util/network.c | 64 |
1 files changed, 41 insertions, 23 deletions
diff --git a/src/util/network.c b/src/util/network.c index 00b0413e2..d36f49cbb 100644 --- a/src/util/network.c +++ b/src/util/network.c | |||
@@ -75,7 +75,7 @@ struct GNUNET_NETWORK_Handle | |||
75 | * Test if the given protocol family is supported by this system. | 75 | * Test if the given protocol family is supported by this system. |
76 | * | 76 | * |
77 | * @param pf protocol family to test (PF_INET, PF_INET6, PF_UNIX) | 77 | * @param pf protocol family to test (PF_INET, PF_INET6, PF_UNIX) |
78 | * @return GNUNET_OK if the PF is supported | 78 | * @return #GNUNET_OK if the PF is supported |
79 | */ | 79 | */ |
80 | int | 80 | int |
81 | GNUNET_NETWORK_test_pf (int pf) | 81 | GNUNET_NETWORK_test_pf (int pf) |
@@ -152,7 +152,7 @@ GNUNET_NETWORK_shorten_unixpath (char *unixpath) | |||
152 | * | 152 | * |
153 | * @param fd socket | 153 | * @param fd socket |
154 | * @param doBlock blocking mode | 154 | * @param doBlock blocking mode |
155 | * @return GNUNET_OK on success, GNUNET_SYSERR on error | 155 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on error |
156 | */ | 156 | */ |
157 | int | 157 | int |
158 | GNUNET_NETWORK_socket_set_blocking (struct GNUNET_NETWORK_Handle *fd, int doBlock) | 158 | GNUNET_NETWORK_socket_set_blocking (struct GNUNET_NETWORK_Handle *fd, int doBlock) |
@@ -201,7 +201,7 @@ GNUNET_NETWORK_socket_set_blocking (struct GNUNET_NETWORK_Handle *fd, int doBloc | |||
201 | * Make a socket non-inheritable to child processes | 201 | * Make a socket non-inheritable to child processes |
202 | * | 202 | * |
203 | * @param h the socket to make non-inheritable | 203 | * @param h the socket to make non-inheritable |
204 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 204 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
205 | * @warning Not implemented on Windows | 205 | * @warning Not implemented on Windows |
206 | */ | 206 | */ |
207 | static int | 207 | static int |
@@ -282,12 +282,12 @@ socket_set_nodelay (const struct GNUNET_NETWORK_Handle *h) | |||
282 | * Perform proper canonical initialization for a network handle. | 282 | * Perform proper canonical initialization for a network handle. |
283 | * Set it to non-blocking, make it non-inheritable to child | 283 | * Set it to non-blocking, make it non-inheritable to child |
284 | * processes, disable SIGPIPE, enable "nodelay" (if non-UNIX | 284 | * processes, disable SIGPIPE, enable "nodelay" (if non-UNIX |
285 | * stream socket) and check that it is smaller than FS_SETSIZE. | 285 | * stream socket) and check that it is smaller than FD_SETSIZE. |
286 | * | 286 | * |
287 | * @param h socket to initialize | 287 | * @param h socket to initialize |
288 | * @param af address family of the socket | 288 | * @param af address family of the socket |
289 | * @param type socket type | 289 | * @param type socket type |
290 | * @return GNUNET_OK on success, GNUNET_SYSERR if initialization | 290 | * @return #GNUNET_OK on success, #GNUNET_SYSERR if initialization |
291 | * failed and the handle was destroyed | 291 | * failed and the handle was destroyed |
292 | */ | 292 | */ |
293 | static int | 293 | static int |
@@ -371,13 +371,13 @@ GNUNET_NETWORK_socket_accept (const struct GNUNET_NETWORK_Handle *desc, | |||
371 | 371 | ||
372 | 372 | ||
373 | /** | 373 | /** |
374 | * Bind to a connected socket | 374 | * Bind a socket to a particular address. |
375 | * | 375 | * |
376 | * @param desc socket to bind | 376 | * @param desc socket to bind |
377 | * @param address address to be bound | 377 | * @param address address to be bound |
378 | * @param address_len length of address | 378 | * @param address_len length of address |
379 | * @param flags flags affecting bind behaviour | 379 | * @param flags flags affecting bind behaviour |
380 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 380 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
381 | */ | 381 | */ |
382 | int | 382 | int |
383 | GNUNET_NETWORK_socket_bind (struct GNUNET_NETWORK_Handle *desc, | 383 | GNUNET_NETWORK_socket_bind (struct GNUNET_NETWORK_Handle *desc, |
@@ -440,8 +440,9 @@ GNUNET_NETWORK_socket_bind (struct GNUNET_NETWORK_Handle *desc, | |||
440 | 440 | ||
441 | /** | 441 | /** |
442 | * Close a socket | 442 | * Close a socket |
443 | * | ||
443 | * @param desc socket | 444 | * @param desc socket |
444 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 445 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
445 | */ | 446 | */ |
446 | int | 447 | int |
447 | GNUNET_NETWORK_socket_close (struct GNUNET_NETWORK_Handle *desc) | 448 | GNUNET_NETWORK_socket_close (struct GNUNET_NETWORK_Handle *desc) |
@@ -510,11 +511,12 @@ GNUNET_NETWORK_socket_box_native (SOCKTYPE fd) | |||
510 | 511 | ||
511 | 512 | ||
512 | /** | 513 | /** |
513 | * Connect a socket | 514 | * Connect a socket to some remote address. |
515 | * | ||
514 | * @param desc socket | 516 | * @param desc socket |
515 | * @param address peer address | 517 | * @param address peer address |
516 | * @param address_len length of address | 518 | * @param address_len length of address |
517 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 519 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
518 | */ | 520 | */ |
519 | int | 521 | int |
520 | GNUNET_NETWORK_socket_connect (const struct GNUNET_NETWORK_Handle *desc, | 522 | GNUNET_NETWORK_socket_connect (const struct GNUNET_NETWORK_Handle *desc, |
@@ -545,7 +547,7 @@ GNUNET_NETWORK_socket_connect (const struct GNUNET_NETWORK_Handle *desc, | |||
545 | * @param optname identifier of the option | 547 | * @param optname identifier of the option |
546 | * @param optval options | 548 | * @param optval options |
547 | * @param optlen length of optval | 549 | * @param optlen length of optval |
548 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 550 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
549 | */ | 551 | */ |
550 | int | 552 | int |
551 | GNUNET_NETWORK_socket_getsockopt (const struct GNUNET_NETWORK_Handle *desc, | 553 | GNUNET_NETWORK_socket_getsockopt (const struct GNUNET_NETWORK_Handle *desc, |
@@ -569,9 +571,10 @@ GNUNET_NETWORK_socket_getsockopt (const struct GNUNET_NETWORK_Handle *desc, | |||
569 | 571 | ||
570 | /** | 572 | /** |
571 | * Listen on a socket | 573 | * Listen on a socket |
574 | * | ||
572 | * @param desc socket | 575 | * @param desc socket |
573 | * @param backlog length of the listen queue | 576 | * @param backlog length of the listen queue |
574 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 577 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
575 | */ | 578 | */ |
576 | int | 579 | int |
577 | GNUNET_NETWORK_socket_listen (const struct GNUNET_NETWORK_Handle *desc, | 580 | GNUNET_NETWORK_socket_listen (const struct GNUNET_NETWORK_Handle *desc, |
@@ -593,8 +596,8 @@ GNUNET_NETWORK_socket_listen (const struct GNUNET_NETWORK_Handle *desc, | |||
593 | /** | 596 | /** |
594 | * How much data is available to be read on this descriptor? | 597 | * How much data is available to be read on this descriptor? |
595 | * | 598 | * |
596 | * Returns GNUNET_NO if no data is available, or on error! | ||
597 | * @param desc socket | 599 | * @param desc socket |
600 | * @returns #GNUNET_NO if no data is available, or on error! | ||
598 | */ | 601 | */ |
599 | ssize_t | 602 | ssize_t |
600 | GNUNET_NETWORK_socket_recvfrom_amount (const struct GNUNET_NETWORK_Handle * | 603 | GNUNET_NETWORK_socket_recvfrom_amount (const struct GNUNET_NETWORK_Handle * |
@@ -622,7 +625,8 @@ GNUNET_NETWORK_socket_recvfrom_amount (const struct GNUNET_NETWORK_Handle * | |||
622 | 625 | ||
623 | 626 | ||
624 | /** | 627 | /** |
625 | * Read data from a connected socket (always non-blocking). | 628 | * Read data from a socket (always non-blocking). |
629 | * | ||
626 | * @param desc socket | 630 | * @param desc socket |
627 | * @param buffer buffer | 631 | * @param buffer buffer |
628 | * @param length length of buffer | 632 | * @param length length of buffer |
@@ -631,9 +635,9 @@ GNUNET_NETWORK_socket_recvfrom_amount (const struct GNUNET_NETWORK_Handle * | |||
631 | * @param addrlen length of the addr | 635 | * @param addrlen length of the addr |
632 | */ | 636 | */ |
633 | ssize_t | 637 | ssize_t |
634 | GNUNET_NETWORK_socket_recvfrom (const struct GNUNET_NETWORK_Handle * desc, | 638 | GNUNET_NETWORK_socket_recvfrom (const struct GNUNET_NETWORK_Handle *desc, |
635 | void *buffer, size_t length, | 639 | void *buffer, size_t length, |
636 | struct sockaddr * src_addr, socklen_t * addrlen) | 640 | struct sockaddr *src_addr, socklen_t *addrlen) |
637 | { | 641 | { |
638 | int ret; | 642 | int ret; |
639 | int flags; | 643 | int flags; |
@@ -655,6 +659,7 @@ GNUNET_NETWORK_socket_recvfrom (const struct GNUNET_NETWORK_Handle * desc, | |||
655 | 659 | ||
656 | /** | 660 | /** |
657 | * Read data from a connected socket (always non-blocking). | 661 | * Read data from a connected socket (always non-blocking). |
662 | * | ||
658 | * @param desc socket | 663 | * @param desc socket |
659 | * @param buffer buffer | 664 | * @param buffer buffer |
660 | * @param length length of buffer | 665 | * @param length length of buffer |
@@ -725,7 +730,7 @@ GNUNET_NETWORK_socket_send (const struct GNUNET_NETWORK_Handle * desc, | |||
725 | * @param length size of the data | 730 | * @param length size of the data |
726 | * @param dest_addr destination address | 731 | * @param dest_addr destination address |
727 | * @param dest_len length of address | 732 | * @param dest_len length of address |
728 | * @return number of bytes sent, GNUNET_SYSERR on error | 733 | * @return number of bytes sent, #GNUNET_SYSERR on error |
729 | */ | 734 | */ |
730 | ssize_t | 735 | ssize_t |
731 | GNUNET_NETWORK_socket_sendto (const struct GNUNET_NETWORK_Handle * desc, | 736 | GNUNET_NETWORK_socket_sendto (const struct GNUNET_NETWORK_Handle * desc, |
@@ -755,12 +760,13 @@ GNUNET_NETWORK_socket_sendto (const struct GNUNET_NETWORK_Handle * desc, | |||
755 | 760 | ||
756 | /** | 761 | /** |
757 | * Set socket option | 762 | * Set socket option |
763 | * | ||
758 | * @param fd socket | 764 | * @param fd socket |
759 | * @param level protocol level of the option | 765 | * @param level protocol level of the option |
760 | * @param option_name option identifier | 766 | * @param option_name option identifier |
761 | * @param option_value value to set | 767 | * @param option_value value to set |
762 | * @param option_len size of option_value | 768 | * @param option_len size of option_value |
763 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 769 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
764 | */ | 770 | */ |
765 | int | 771 | int |
766 | GNUNET_NETWORK_socket_setsockopt (struct GNUNET_NETWORK_Handle *fd, int level, | 772 | GNUNET_NETWORK_socket_setsockopt (struct GNUNET_NETWORK_Handle *fd, int level, |
@@ -829,7 +835,7 @@ GNUNET_NETWORK_socket_shutdown (struct GNUNET_NETWORK_Handle *desc, int how) | |||
829 | * reduces the OS send buffers to zero. | 835 | * reduces the OS send buffers to zero. |
830 | * | 836 | * |
831 | * @param desc socket | 837 | * @param desc socket |
832 | * @return GNUNET_OK on success, GNUNET_SYSERR otherwise | 838 | * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise |
833 | */ | 839 | */ |
834 | int | 840 | int |
835 | GNUNET_NETWORK_socket_disable_corking (struct GNUNET_NETWORK_Handle *desc) | 841 | GNUNET_NETWORK_socket_disable_corking (struct GNUNET_NETWORK_Handle *desc) |
@@ -867,6 +873,7 @@ GNUNET_NETWORK_socket_disable_corking (struct GNUNET_NETWORK_Handle *desc) | |||
867 | 873 | ||
868 | /** | 874 | /** |
869 | * Reset FD set | 875 | * Reset FD set |
876 | * | ||
870 | * @param fds fd set | 877 | * @param fds fd set |
871 | */ | 878 | */ |
872 | void | 879 | void |
@@ -879,8 +886,10 @@ GNUNET_NETWORK_fdset_zero (struct GNUNET_NETWORK_FDSet *fds) | |||
879 | #endif | 886 | #endif |
880 | } | 887 | } |
881 | 888 | ||
889 | |||
882 | /** | 890 | /** |
883 | * Add a socket to the FD set | 891 | * Add a socket to the FD set |
892 | * | ||
884 | * @param fds fd set | 893 | * @param fds fd set |
885 | * @param desc socket to add | 894 | * @param desc socket to add |
886 | */ | 895 | */ |
@@ -896,6 +905,7 @@ GNUNET_NETWORK_fdset_set (struct GNUNET_NETWORK_FDSet *fds, | |||
896 | 905 | ||
897 | /** | 906 | /** |
898 | * Check whether a socket is part of the fd set | 907 | * Check whether a socket is part of the fd set |
908 | * | ||
899 | * @param fds fd set | 909 | * @param fds fd set |
900 | * @param desc socket | 910 | * @param desc socket |
901 | * @return 0 if the FD is not set | 911 | * @return 0 if the FD is not set |
@@ -910,6 +920,7 @@ GNUNET_NETWORK_fdset_isset (const struct GNUNET_NETWORK_FDSet *fds, | |||
910 | 920 | ||
911 | /** | 921 | /** |
912 | * Add one fd set to another | 922 | * Add one fd set to another |
923 | * | ||
913 | * @param dst the fd set to add to | 924 | * @param dst the fd set to add to |
914 | * @param src the fd set to add from | 925 | * @param src the fd set to add from |
915 | */ | 926 | */ |
@@ -977,6 +988,7 @@ GNUNET_NETWORK_get_fd (struct GNUNET_NETWORK_Handle *desc) | |||
977 | return desc->fd; | 988 | return desc->fd; |
978 | } | 989 | } |
979 | 990 | ||
991 | |||
980 | /** | 992 | /** |
981 | * Return sockaddr for this network handle | 993 | * Return sockaddr for this network handle |
982 | * | 994 | * |
@@ -989,6 +1001,7 @@ GNUNET_NETWORK_get_addr (struct GNUNET_NETWORK_Handle *desc) | |||
989 | return desc->addr; | 1001 | return desc->addr; |
990 | } | 1002 | } |
991 | 1003 | ||
1004 | |||
992 | /** | 1005 | /** |
993 | * Return sockaddr length for this network handle | 1006 | * Return sockaddr length for this network handle |
994 | * | 1007 | * |
@@ -1000,6 +1013,8 @@ GNUNET_NETWORK_get_addrlen (struct GNUNET_NETWORK_Handle *desc) | |||
1000 | { | 1013 | { |
1001 | return desc->addrlen; | 1014 | return desc->addrlen; |
1002 | } | 1015 | } |
1016 | |||
1017 | |||
1003 | /** | 1018 | /** |
1004 | * Copy a native fd set | 1019 | * Copy a native fd set |
1005 | * | 1020 | * |
@@ -1036,7 +1051,7 @@ GNUNET_NETWORK_fdset_set_native (struct GNUNET_NETWORK_FDSet *to, int nfd) | |||
1036 | * | 1051 | * |
1037 | * @param to set to test, NULL for empty set | 1052 | * @param to set to test, NULL for empty set |
1038 | * @param nfd native FD to test, or -1 for none | 1053 | * @param nfd native FD to test, or -1 for none |
1039 | * @return GNUNET_YES if FD is set in the set | 1054 | * @return #GNUNET_YES if FD is set in the set |
1040 | */ | 1055 | */ |
1041 | int | 1056 | int |
1042 | GNUNET_NETWORK_fdset_test_native (const struct GNUNET_NETWORK_FDSet *to, | 1057 | GNUNET_NETWORK_fdset_test_native (const struct GNUNET_NETWORK_FDSet *to, |
@@ -1078,7 +1093,7 @@ GNUNET_NETWORK_fdset_handle_set (struct GNUNET_NETWORK_FDSet *fds, | |||
1078 | * Check if a file handle is part of an fd set | 1093 | * Check if a file handle is part of an fd set |
1079 | * @param fds fd set | 1094 | * @param fds fd set |
1080 | * @param h file handle | 1095 | * @param h file handle |
1081 | * @return GNUNET_YES if the file handle is part of the set | 1096 | * @return #GNUNET_YES if the file handle is part of the set |
1082 | */ | 1097 | */ |
1083 | int | 1098 | int |
1084 | GNUNET_NETWORK_fdset_handle_isset (const struct GNUNET_NETWORK_FDSet *fds, | 1099 | GNUNET_NETWORK_fdset_handle_isset (const struct GNUNET_NETWORK_FDSet *fds, |
@@ -1099,7 +1114,7 @@ GNUNET_NETWORK_fdset_handle_isset (const struct GNUNET_NETWORK_FDSet *fds, | |||
1099 | * Checks if two fd sets overlap | 1114 | * Checks if two fd sets overlap |
1100 | * @param fds1 first fd set | 1115 | * @param fds1 first fd set |
1101 | * @param fds2 second fd set | 1116 | * @param fds2 second fd set |
1102 | * @return GNUNET_YES if they do overlap, GNUNET_NO otherwise | 1117 | * @return #GNUNET_YES if they do overlap, #GNUNET_NO otherwise |
1103 | */ | 1118 | */ |
1104 | int | 1119 | int |
1105 | GNUNET_NETWORK_fdset_overlap (const struct GNUNET_NETWORK_FDSet *fds1, | 1120 | GNUNET_NETWORK_fdset_overlap (const struct GNUNET_NETWORK_FDSet *fds1, |
@@ -1170,6 +1185,7 @@ GNUNET_NETWORK_fdset_overlap (const struct GNUNET_NETWORK_FDSet *fds1, | |||
1170 | 1185 | ||
1171 | /** | 1186 | /** |
1172 | * Creates an fd set | 1187 | * Creates an fd set |
1188 | * | ||
1173 | * @return a new fd set | 1189 | * @return a new fd set |
1174 | */ | 1190 | */ |
1175 | struct GNUNET_NETWORK_FDSet * | 1191 | struct GNUNET_NETWORK_FDSet * |
@@ -1188,6 +1204,7 @@ GNUNET_NETWORK_fdset_create () | |||
1188 | 1204 | ||
1189 | /** | 1205 | /** |
1190 | * Releases the associated memory of an fd set | 1206 | * Releases the associated memory of an fd set |
1207 | * | ||
1191 | * @param fds fd set | 1208 | * @param fds fd set |
1192 | */ | 1209 | */ |
1193 | void | 1210 | void |
@@ -1233,13 +1250,14 @@ _selector (LPVOID p) | |||
1233 | } | 1250 | } |
1234 | #endif | 1251 | #endif |
1235 | 1252 | ||
1253 | |||
1236 | /** | 1254 | /** |
1237 | * Check if sockets or pipes meet certain conditions | 1255 | * Check if sockets or pipes meet certain conditions |
1238 | * @param rfds set of sockets or pipes to be checked for readability | 1256 | * @param rfds set of sockets or pipes to be checked for readability |
1239 | * @param wfds set of sockets or pipes to be checked for writability | 1257 | * @param wfds set of sockets or pipes to be checked for writability |
1240 | * @param efds set of sockets or pipes to be checked for exceptions | 1258 | * @param efds set of sockets or pipes to be checked for exceptions |
1241 | * @param timeout relative value when to return | 1259 | * @param timeout relative value when to return |
1242 | * @return number of selected sockets or pipes, GNUNET_SYSERR on error | 1260 | * @return number of selected sockets or pipes, #GNUNET_SYSERR on error |
1243 | */ | 1261 | */ |
1244 | int | 1262 | int |
1245 | GNUNET_NETWORK_socket_select (struct GNUNET_NETWORK_FDSet *rfds, | 1263 | GNUNET_NETWORK_socket_select (struct GNUNET_NETWORK_FDSet *rfds, |