gnunet_network_lib.h (15707B)
1 /* 2 This file is part of GNUnet. 3 Copyright (C) 2009-2013, 2022 GNUnet e.V. 4 5 GNUnet is free software: you can redistribute it and/or modify it 6 under the terms of the GNU Affero General Public License as published 7 by the Free Software Foundation, either version 3 of the License, 8 or (at your 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 Affero General Public License for more details. 14 15 You should have received a copy of the GNU Affero General Public License 16 along with this program. If not, see <http://www.gnu.org/licenses/>. 17 18 SPDX-License-Identifier: AGPL3.0-or-later 19 */ 20 21 /** 22 * @addtogroup libgnunetutil 23 * Multi-function utilities library for GNUnet programs 24 * @{ 25 * 26 * @addtogroup networking 27 * @{ 28 * 29 * @author Nils Durner 30 * @author Tobias Frisch 31 * 32 * @file 33 * Basic low-level networking interface 34 * 35 * @defgroup network Network library 36 * Basic low-level networking interface 37 * @{ 38 */ 39 #ifndef GNUNET_NETWORK_LIB_H 40 #define GNUNET_NETWORK_LIB_H 41 42 #include "gnunet_common.h" 43 #ifdef __cplusplus 44 extern "C" 45 { 46 #if 0 /* keep Emacsens' auto-indent happy */ 47 } 48 #endif 49 #endif 50 51 //#ifdef HAVE_SYS_SELECT_H 52 /* 53 * Include "sys/select.h" because it is required to use 54 * "fd_set" in "struct GNUNET_NETWORK_FDSet"! 55 */ 56 57 #include <sys/select.h> 58 //#endif 59 #ifdef HAVE_SYS_SOCKET_H 60 #include <sys/socket.h> 61 #endif 62 #ifdef HAVE_SYS_UN_H 63 #include <sys/un.h> 64 #endif 65 66 /** 67 * @brief handle to a socket 68 */ 69 struct GNUNET_NETWORK_Handle; 70 71 72 /** 73 * @brief collection of IO descriptors 74 */ 75 struct GNUNET_NETWORK_FDSet 76 { 77 /** 78 * Maximum number of any socket descriptor in the set (plus one) 79 */ 80 int nsds; 81 82 /** 83 * Bitset with the descriptors. 84 */ 85 fd_set sds; 86 87 }; 88 89 #include "gnunet_disk_lib.h" 90 #include "gnunet_time_lib.h" 91 92 /** 93 * Test if the given protocol family is supported by this system. 94 * 95 * @param pf protocol family to test (PF_INET, PF_INET6, PF_UNIX) 96 * @return #GNUNET_OK if the PF is supported 97 */ 98 enum GNUNET_GenericReturnValue 99 GNUNET_NETWORK_test_pf (int pf); 100 101 102 /** 103 * Given a unixpath that is too long (larger than UNIX_PATH_MAX), 104 * shorten it to an acceptable length while keeping it unique 105 * and making sure it remains a valid filename (if possible). 106 * 107 * @param unixpath long path, will be freed (or same pointer returned 108 * with moved 0-termination). 109 * @return shortened unixpath, NULL on error 110 */ 111 char * 112 GNUNET_NETWORK_shorten_unixpath (char *unixpath); 113 114 115 /** 116 * If services crash, they can leave a unix domain socket file on the 117 * disk. This needs to be manually removed, because otherwise both 118 * bind() and connect() for the respective address will fail. In this 119 * function, we test if such a left-over file exists, and if so, 120 * remove it (unless there is a listening service at the address). 121 * 122 * @param un unix domain socket address to check 123 */ 124 void 125 GNUNET_NETWORK_unix_precheck (const struct sockaddr_un *un); 126 127 128 /** 129 * Accept a new connection on a socket. Configure it for non-blocking 130 * IO and mark it as non-inheritable to child processes (set the 131 * close-on-exec flag). 132 * 133 * @param desc bound socket 134 * @param address address of the connecting peer, may be NULL 135 * @param address_len length of address 136 * @return client socket 137 */ 138 struct GNUNET_NETWORK_Handle * 139 GNUNET_NETWORK_socket_accept (const struct GNUNET_NETWORK_Handle *desc, 140 struct sockaddr *address, 141 socklen_t *address_len); 142 143 144 /** 145 * Box a native socket (and check that it is a socket). 146 * 147 * @param fd socket to box 148 * @return NULL on error (including not supported on target platform) 149 */ 150 struct GNUNET_NETWORK_Handle * 151 GNUNET_NETWORK_socket_box_native (int fd); 152 153 154 /** 155 * Set if a socket should use blocking or non-blocking IO. 156 * 157 * @param fd socket 158 * @param doBlock blocking mode 159 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error 160 */ 161 enum GNUNET_GenericReturnValue 162 GNUNET_NETWORK_socket_set_blocking (struct GNUNET_NETWORK_Handle *fd, 163 int doBlock); 164 165 166 /** 167 * Bind a socket to a particular address. 168 * 169 * @param desc socket to bind 170 * @param address address to be bound 171 * @param address_len length of @a address 172 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 173 */ 174 enum GNUNET_GenericReturnValue 175 GNUNET_NETWORK_socket_bind (struct GNUNET_NETWORK_Handle *desc, 176 const struct sockaddr *address, 177 socklen_t address_len); 178 179 /** 180 * Close a socket. 181 * 182 * @param desc socket to close 183 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 184 */ 185 enum GNUNET_GenericReturnValue 186 GNUNET_NETWORK_socket_close (struct GNUNET_NETWORK_Handle *desc); 187 188 189 /** 190 * Only free memory of a socket, keep the file descriptor untouched. 191 * 192 * @param desc socket 193 */ 194 void 195 GNUNET_NETWORK_socket_free_memory_only_ (struct GNUNET_NETWORK_Handle *desc); 196 197 198 /** 199 * Connect a socket to some remote address. 200 * 201 * @param desc socket to connect 202 * @param address peer address 203 * @param address_len of @a address 204 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 205 */ 206 enum GNUNET_GenericReturnValue 207 GNUNET_NETWORK_socket_connect (const struct GNUNET_NETWORK_Handle *desc, 208 const struct sockaddr *address, 209 socklen_t address_len); 210 211 212 /** 213 * Get socket options 214 * 215 * @param desc socket to inspect 216 * @param level protocol level of the option 217 * @param optname identifier of the option 218 * @param optval options 219 * @param optlen length of optval 220 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 221 */ 222 enum GNUNET_GenericReturnValue 223 GNUNET_NETWORK_socket_getsockopt (const struct GNUNET_NETWORK_Handle *desc, 224 int level, 225 int optname, 226 void *optval, 227 socklen_t *optlen); 228 229 230 /** 231 * Listen on a socket 232 * 233 * @param desc socket to start listening on 234 * @param backlog length of the listen queue 235 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 236 */ 237 enum GNUNET_GenericReturnValue 238 GNUNET_NETWORK_socket_listen (const struct GNUNET_NETWORK_Handle *desc, 239 int backlog); 240 241 242 /** 243 * How much data is available to be read on this descriptor? 244 * 245 * @param desc socket 246 * @returns #GNUNET_SYSERR if no data is available, or on error! 247 */ 248 ssize_t 249 GNUNET_NETWORK_socket_recvfrom_amount (const struct 250 GNUNET_NETWORK_Handle *desc); 251 252 253 /** 254 * Read data from a socket (always non-blocking). 255 * 256 * @param desc socket 257 * @param buffer buffer 258 * @param length length of buffer 259 * @param src_addr either the source to recv from, or all zeroes 260 * to be filled in by recvfrom 261 * @param addrlen length of the addr 262 */ 263 ssize_t 264 GNUNET_NETWORK_socket_recvfrom (const struct GNUNET_NETWORK_Handle *desc, 265 void *buffer, 266 size_t length, 267 struct sockaddr *src_addr, 268 socklen_t *addrlen); 269 270 271 /** 272 * Read data from a connected socket (always non-blocking). 273 * 274 * @param desc socket 275 * @param buffer buffer 276 * @param length length of buffer 277 * @return number of bytes read 278 */ 279 ssize_t 280 GNUNET_NETWORK_socket_recv (const struct GNUNET_NETWORK_Handle *desc, 281 void *buffer, 282 size_t length); 283 284 285 /** 286 * Check if sockets meet certain conditions. 287 * 288 * @param rfds set of sockets to be checked for readability 289 * @param wfds set of sockets to be checked for writability 290 * @param efds set of sockets to be checked for exceptions 291 * @param timeout relative value when to return 292 * @return number of selected sockets, #GNUNET_SYSERR on error 293 */ 294 int 295 GNUNET_NETWORK_socket_select (struct GNUNET_NETWORK_FDSet *rfds, 296 struct GNUNET_NETWORK_FDSet *wfds, 297 struct GNUNET_NETWORK_FDSet *efds, 298 struct GNUNET_TIME_Relative timeout); 299 300 301 /** 302 * Send data (always non-blocking). 303 * 304 * @param desc socket 305 * @param buffer data to send 306 * @param length size of the buffer 307 * @return number of bytes sent, #GNUNET_SYSERR on error 308 */ 309 ssize_t 310 GNUNET_NETWORK_socket_send (const struct GNUNET_NETWORK_Handle *desc, 311 const void *buffer, 312 size_t length); 313 314 315 /** 316 * Send data to a particular destination (always non-blocking). 317 * This function only works for UDP sockets. 318 * 319 * @param desc socket 320 * @param message data to send 321 * @param length size of the data in @a message 322 * @param dest_addr destination address 323 * @param dest_len length of @a dest_addr 324 * @return number of bytes sent, #GNUNET_SYSERR on error 325 */ 326 ssize_t 327 GNUNET_NETWORK_socket_sendto (const struct GNUNET_NETWORK_Handle *desc, 328 const void *message, 329 size_t length, 330 const struct sockaddr *dest_addr, 331 socklen_t dest_len); 332 333 334 /** 335 * Set socket option 336 * 337 * @param fd socket 338 * @param level protocol level of the option 339 * @param option_name option identifier 340 * @param option_value value to set 341 * @param option_len size of @a option_value 342 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 343 */ 344 int 345 GNUNET_NETWORK_socket_setsockopt (struct GNUNET_NETWORK_Handle *fd, 346 int level, 347 int option_name, 348 const void *option_value, 349 socklen_t option_len); 350 351 352 /** 353 * Shut down socket operations 354 * 355 * @param desc socket 356 * @param how type of shutdown 357 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 358 */ 359 enum GNUNET_GenericReturnValue 360 GNUNET_NETWORK_socket_shutdown (struct GNUNET_NETWORK_Handle *desc, 361 int how); 362 363 364 /** 365 * Disable the "CORK" feature for communication with the given socket, 366 * forcing the OS to immediately flush the buffer on transmission 367 * instead of potentially buffering multiple messages. Essentially 368 * reduces the OS send buffers to zero. 369 * 370 * @param desc socket 371 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise 372 */ 373 enum GNUNET_GenericReturnValue 374 GNUNET_NETWORK_socket_disable_corking (struct GNUNET_NETWORK_Handle *desc); 375 376 377 /** 378 * Create a new socket. Configure it for non-blocking IO and 379 * mark it as non-inheritable to child processes (set the 380 * close-on-exec flag). 381 * 382 * @param domain domain of the socket 383 * @param type socket type 384 * @param protocol network protocol 385 * @return new socket, NULL on error 386 */ 387 struct GNUNET_NETWORK_Handle * 388 GNUNET_NETWORK_socket_create (int domain, 389 int type, 390 int protocol); 391 392 393 /** 394 * Reset FD set (clears all file descriptors). 395 * 396 * @param fds fd set to clear 397 */ 398 void 399 GNUNET_NETWORK_fdset_zero (struct GNUNET_NETWORK_FDSet *fds); 400 401 402 /** 403 * Add a socket to the FD set 404 * 405 * @param fds fd set 406 * @param desc socket to add 407 */ 408 void 409 GNUNET_NETWORK_fdset_set (struct GNUNET_NETWORK_FDSet *fds, 410 const struct GNUNET_NETWORK_Handle *desc); 411 412 413 /** 414 * Check whether a socket is part of the fd set 415 * 416 * @param fds fd set 417 * @param desc socket 418 * @return #GNUNET_YES if the socket is in the set 419 */ 420 int 421 GNUNET_NETWORK_fdset_isset (const struct GNUNET_NETWORK_FDSet *fds, 422 const struct GNUNET_NETWORK_Handle *desc); 423 424 425 /** 426 * Add one fd set to another (computes the union). 427 * 428 * @param dst the fd set to add to 429 * @param src the fd set to add from 430 */ 431 void 432 GNUNET_NETWORK_fdset_add (struct GNUNET_NETWORK_FDSet *dst, 433 const struct GNUNET_NETWORK_FDSet *src); 434 435 436 /** 437 * Copy one fd set to another 438 * 439 * @param to destination 440 * @param from source 441 */ 442 void 443 GNUNET_NETWORK_fdset_copy (struct GNUNET_NETWORK_FDSet *to, 444 const struct GNUNET_NETWORK_FDSet *from); 445 446 447 /** 448 * Return file descriptor for this network handle 449 * 450 * @param desc wrapper to process 451 * @return POSIX file descriptor 452 */ 453 int 454 GNUNET_NETWORK_get_fd (const struct GNUNET_NETWORK_Handle *desc); 455 456 457 /** 458 * Return the sockaddr for this network handle 459 * 460 * @param desc wrapper to process 461 * @return POSIX file descriptor 462 */ 463 struct sockaddr* 464 GNUNET_NETWORK_get_addr (const struct GNUNET_NETWORK_Handle *desc); 465 466 467 /** 468 * Return sockaddr length for this network handle 469 * 470 * @param desc wrapper to process 471 * @return socklen_t for sockaddr 472 */ 473 socklen_t 474 GNUNET_NETWORK_get_addrlen (const struct GNUNET_NETWORK_Handle *desc); 475 476 477 /** 478 * Copy a native fd set into the GNUnet representation. 479 * 480 * @param to destination 481 * @param from native source set 482 * @param nfds the biggest socket number in from + 1 483 */ 484 void 485 GNUNET_NETWORK_fdset_copy_native (struct GNUNET_NETWORK_FDSet *to, 486 const fd_set *from, 487 int nfds); 488 489 490 /** 491 * Set a native fd in a set 492 * 493 * @param to destination 494 * @param nfd native FD to set 495 */ 496 void 497 GNUNET_NETWORK_fdset_set_native (struct GNUNET_NETWORK_FDSet *to, 498 int nfd); 499 500 501 /** 502 * Test native fd in a set 503 * 504 * @param to set to test, NULL for empty set 505 * @param nfd native FD to test, -1 for none 506 * @return #GNUNET_YES if to contains nfd 507 */ 508 int 509 GNUNET_NETWORK_fdset_test_native (const struct GNUNET_NETWORK_FDSet *to, 510 int nfd); 511 512 513 /** 514 * Add a file handle to the fd set 515 * 516 * @param fds fd set 517 * @param h the file handle to add 518 */ 519 void 520 GNUNET_NETWORK_fdset_handle_set (struct GNUNET_NETWORK_FDSet *fds, 521 const struct GNUNET_DISK_FileHandle *h); 522 523 524 /** 525 * Add a file handle to the fd set 526 * On W32: ensure that the handle is first in the array. 527 * 528 * @param fds fd set 529 * @param h the file handle to add 530 */ 531 void 532 GNUNET_NETWORK_fdset_handle_set_first (struct GNUNET_NETWORK_FDSet *fds, 533 const struct GNUNET_DISK_FileHandle *h); 534 535 536 /** 537 * Check if a file handle is part of an fd set 538 * 539 * @param fds fd set 540 * @param h file handle 541 * @return #GNUNET_YES if the file handle is part of the set 542 */ 543 int 544 GNUNET_NETWORK_fdset_handle_isset (const struct GNUNET_NETWORK_FDSet *fds, 545 const struct GNUNET_DISK_FileHandle *h); 546 547 548 /** 549 * Checks if two fd sets overlap 550 * 551 * @param fds1 first fd set 552 * @param fds2 second fd set 553 * @return #GNUNET_YES if they do overlap, #GNUNET_NO otherwise 554 */ 555 int 556 GNUNET_NETWORK_fdset_overlap (const struct GNUNET_NETWORK_FDSet *fds1, 557 const struct GNUNET_NETWORK_FDSet *fds2); 558 559 560 /** 561 * Creates an fd set 562 * 563 * @return a new fd set 564 */ 565 struct GNUNET_NETWORK_FDSet * 566 GNUNET_NETWORK_fdset_create (void); 567 568 569 /** 570 * Releases the associated memory of an fd set 571 * 572 * @param fds fd set 573 */ 574 void 575 GNUNET_NETWORK_fdset_destroy (struct GNUNET_NETWORK_FDSet *fds); 576 577 578 /** 579 * Test if the given @a port is available. 580 * 581 * @param ipproto transport protocol to test (e.g. IPPROTO_TCP) 582 * @param port port number to test 583 * @return #GNUNET_OK if the port is available, #GNUNET_NO if not 584 */ 585 int 586 GNUNET_NETWORK_test_port_free (int ipproto, 587 uint16_t port); 588 589 590 #if 0 /* keep Emacsens' auto-indent happy */ 591 { 592 #endif 593 #ifdef __cplusplus 594 } 595 #endif 596 597 #endif /* GNUNET_NETWORK_LIB_H */ 598 599 /** @} */ /* end of group */ 600 601 /** @} */ /* end of group addition */ 602 603 /** @} */ /* end of group addition */