src/include/gnunet_network_lib.h

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