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
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @author Nils Durner
  23  *
  24  * @file
  25  * Basic low-level networking interface
  26  *
  27  * @defgroup network  Network library
  28  * Basic low-level networking interface
  29  * @{
  30  */
  31 #ifndef GNUNET_NETWORK_LIB_H
  32 #define GNUNET_NETWORK_LIB_H
  33
  34 #ifdef __cplusplus
  35 extern "C"
  36 {
  37 #if 0                           /* keep Emacsens' auto-indent happy */
  38 }
  39 #endif
  40 #endif
  41
  42
  43 /**
  44  * @brief handle to a socket
  45  */
  46 struct GNUNET_NETWORK_Handle;
  47
  48
  49 /**
  50  * @brief collection of IO descriptors
  51  */
  52 struct GNUNET_NETWORK_FDSet
  53 {
  54
  55   /**
  56    * Maximum number of any socket descriptor in the set (plus one)
  57    */
  58   int nsds;
  59
  60   /**
  61    * Bitset with the descriptors.
  62    */
  63   fd_set sds;
  64
  65 #ifdef WINDOWS
  66   /**
  67    * Array of file handles (from pipes) that are also in
  68    * the FDSet.  Needed as those cannot go into @e sds
  69    * on W32.
  70    */
  71   const struct GNUNET_DISK_FileHandle **handles;
  72
  73   /**
  74    * Size of the @e handles array
  75    */
  76   unsigned int handles_size;
  77
  78   /**
  79    * Number of @e handles slots in use. Always
  80    * smaller than @e handles_size.
  81    */
  82   unsigned int handles_pos;
  83
  84 #endif
  85
  86 };
  87
  88 #include "gnunet_disk_lib.h"
  89 #include "gnunet_time_lib.h"
  90
  91 /**
  92  * Test if the given protocol family is supported by this system.
  93  *
  94  * @param pf protocol family to test (PF_INET, PF_INET6, PF_UNIX)
  95  * @return #GNUNET_OK if the PF is supported
  96  */
  97 int
  98 GNUNET_NETWORK_test_pf (int pf);
  99
 100
 101 /**
 102  * Given a unixpath that is too long (larger than UNIX_PATH_MAX),
 103  * shorten it to an acceptable length while keeping it unique
 104  * and making sure it remains a valid filename (if possible).
 105  *
 106  * @param unixpath long path, will be freed (or same pointer returned
 107  *        with moved 0-termination).
 108  * @return shortened unixpath, NULL on error
 109  */
 110 char *
 111 GNUNET_NETWORK_shorten_unixpath (char *unixpath);
 112
 113
 114 #ifndef WINDOWS
 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 #endif
 127
 128
 129 /**
 130  * Accept a new connection on a socket.  Configure it for non-blocking
 131  * IO and mark it as non-inheritable to child processes (set the
 132  * close-on-exec flag).
 133  *
 134  * @param desc bound socket
 135  * @param address address of the connecting peer, may be NULL
 136  * @param address_len length of address
 137  * @return client socket
 138  */
 139 struct GNUNET_NETWORK_Handle *
 140 GNUNET_NETWORK_socket_accept (const struct GNUNET_NETWORK_Handle *desc,
 141                               struct sockaddr *address,
 142                               socklen_t *address_len);
 143
 144
 145 /**
 146  * Box a native socket (and check that it is a socket).
 147  *
 148  * @param fd socket to box
 149  * @return NULL on error (including not supported on target platform)
 150  */
 151 struct GNUNET_NETWORK_Handle *
 152 GNUNET_NETWORK_socket_box_native (SOCKTYPE fd);
 153
 154
 155 /**
 156  * Set if a socket should use blocking or non-blocking IO.
 157  *
 158  * @param fd socket
 159  * @param doBlock blocking mode
 160  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
 161  */
 162 int
 163 GNUNET_NETWORK_socket_set_blocking (struct GNUNET_NETWORK_Handle *fd,
 164                                     int doBlock);
 165
 166
 167 /**
 168  * Bind a socket to a particular address.
 169  *
 170  * @param desc socket to bind
 171  * @param address address to be bound
 172  * @param address_len length of @a address
 173  * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
 174  */
 175 int
 176 GNUNET_NETWORK_socket_bind (struct GNUNET_NETWORK_Handle *desc,
 177                             const struct sockaddr *address,
 178                             socklen_t address_len);
 179
 180 /**
 181  * Close a socket.
 182  *
 183  * @param desc socket to close
 184  * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
 185  */
 186 int
 187 GNUNET_NETWORK_socket_close (struct GNUNET_NETWORK_Handle *desc);
 188
 189
 190 /**
 191  * Only free memory of a socket, keep the file descriptor untouched.
 192  *
 193  * @param desc socket
 194  */
 195 void
 196 GNUNET_NETWORK_socket_free_memory_only_ (struct GNUNET_NETWORK_Handle *desc);
 197
 198
 199 /**
 200  * Connect a socket to some remote address.
 201  *
 202  * @param desc socket to connect
 203  * @param address peer address
 204  * @param address_len of @a address
 205  * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
 206  */
 207 int
 208 GNUNET_NETWORK_socket_connect (const struct GNUNET_NETWORK_Handle *desc,
 209                                const struct sockaddr *address,
 210                                socklen_t address_len);
 211
 212
 213 /**
 214  * Get socket options
 215  *
 216  * @param desc socket to inspect
 217  * @param level protocol level of the option
 218  * @param optname identifier of the option
 219  * @param optval options
 220  * @param optlen length of optval
 221  * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
 222  */
 223 int
 224 GNUNET_NETWORK_socket_getsockopt (const struct GNUNET_NETWORK_Handle *desc,
 225                                   int level,
 226                                   int optname,
 227                                   void *optval,
 228                                   socklen_t *optlen);
 229
 230
 231 /**
 232  * Listen on a socket
 233  *
 234  * @param desc socket to start listening on
 235  * @param backlog length of the listen queue
 236  * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
 237  */
 238 int
 239 GNUNET_NETWORK_socket_listen (const struct GNUNET_NETWORK_Handle *desc,
 240                               int backlog);
 241
 242
 243 /**
 244  * How much data is available to be read on this descriptor?
 245  *
 246  * @param desc socket
 247  * @returns #GNUNET_SYSERR if no data is available, or on error!
 248  */
 249 ssize_t
 250 GNUNET_NETWORK_socket_recvfrom_amount (const struct 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 int
 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 int
 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 #if WINDOWS
 414 /**
 415  * Add a W32 file handle to the fd set
 416  *
 417  * @param fds fd set
 418  * @param h the file handle to add
 419  */
 420 void
 421 GNUNET_NETWORK_fdset_handle_set_native_w32_handle (struct GNUNET_NETWORK_FDSet *fds,
 422                                                    HANDLE h);
 423 #endif
 424
 425
 426 /**
 427  * Check whether a socket is part of the fd set
 428  *
 429  * @param fds fd set
 430  * @param desc socket
 431  * @return #GNUNET_YES if the socket is in the set
 432  */
 433 int
 434 GNUNET_NETWORK_fdset_isset (const struct GNUNET_NETWORK_FDSet *fds,
 435                             const struct GNUNET_NETWORK_Handle *desc);
 436
 437
 438 /**
 439  * Add one fd set to another (computes the union).
 440  *
 441  * @param dst the fd set to add to
 442  * @param src the fd set to add from
 443  */
 444 void
 445 GNUNET_NETWORK_fdset_add (struct GNUNET_NETWORK_FDSet *dst,
 446                           const struct GNUNET_NETWORK_FDSet *src);
 447
 448
 449 /**
 450  * Copy one fd set to another
 451  *
 452  * @param to destination
 453  * @param from source
 454  */
 455 void
 456 GNUNET_NETWORK_fdset_copy (struct GNUNET_NETWORK_FDSet *to,
 457                            const struct GNUNET_NETWORK_FDSet *from);
 458
 459
 460 /**
 461  * Return file descriptor for this network handle
 462  *
 463  * @param desc wrapper to process
 464  * @return POSIX file descriptor
 465  */
 466 int
 467 GNUNET_NETWORK_get_fd (const struct GNUNET_NETWORK_Handle *desc);
 468
 469
 470 /**
 471  * Return the sockaddr for this network handle
 472  *
 473  * @param desc wrapper to process
 474  * @return POSIX file descriptor
 475  */
 476 struct sockaddr*
 477 GNUNET_NETWORK_get_addr (const struct GNUNET_NETWORK_Handle *desc);
 478
 479
 480 /**
 481  * Return sockaddr length for this network handle
 482  *
 483  * @param desc wrapper to process
 484  * @return socklen_t for sockaddr
 485  */
 486 socklen_t
 487 GNUNET_NETWORK_get_addrlen (const struct GNUNET_NETWORK_Handle *desc);
 488
 489
 490 /**
 491  * Copy a native fd set into the GNUnet representation.
 492  *
 493  * @param to destination
 494  * @param from native source set
 495  * @param nfds the biggest socket number in from + 1
 496  */
 497 void
 498 GNUNET_NETWORK_fdset_copy_native (struct GNUNET_NETWORK_FDSet *to,
 499                                   const fd_set *from,
 500                                   int nfds);
 501
 502
 503 /**
 504  * Set a native fd in a set
 505  *
 506  * @param to destination
 507  * @param nfd native FD to set
 508  */
 509 void
 510 GNUNET_NETWORK_fdset_set_native (struct GNUNET_NETWORK_FDSet *to,
 511                                  int nfd);
 512
 513
 514 /**
 515  * Test native fd in a set
 516  *
 517  * @param to set to test, NULL for empty set
 518  * @param nfd native FD to test, -1 for none
 519  * @return #GNUNET_YES if to contains nfd
 520  */
 521 int
 522 GNUNET_NETWORK_fdset_test_native (const struct GNUNET_NETWORK_FDSet *to,
 523                                   int nfd);
 524
 525
 526 /**
 527  * Add a file handle to the fd set
 528  *
 529  * @param fds fd set
 530  * @param h the file handle to add
 531  */
 532 void
 533 GNUNET_NETWORK_fdset_handle_set (struct GNUNET_NETWORK_FDSet *fds,
 534                                  const struct GNUNET_DISK_FileHandle *h);
 535
 536
 537 /**
 538  * Add a file handle to the fd set
 539  * On W32: ensure that the handle is first in the array.
 540  *
 541  * @param fds fd set
 542  * @param h the file handle to add
 543  */
 544 void
 545 GNUNET_NETWORK_fdset_handle_set_first (struct GNUNET_NETWORK_FDSet *fds,
 546                                        const struct GNUNET_DISK_FileHandle *h);
 547
 548
 549 /**
 550  * Check if a file handle is part of an fd set
 551  *
 552  * @param fds fd set
 553  * @param h file handle
 554  * @return #GNUNET_YES if the file handle is part of the set
 555  */
 556 int
 557 GNUNET_NETWORK_fdset_handle_isset (const struct GNUNET_NETWORK_FDSet *fds,
 558                                    const struct GNUNET_DISK_FileHandle *h);
 559
 560
 561 /**
 562  * Checks if two fd sets overlap
 563  *
 564  * @param fds1 first fd set
 565  * @param fds2 second fd set
 566  * @return #GNUNET_YES if they do overlap, #GNUNET_NO otherwise
 567  */
 568 int
 569 GNUNET_NETWORK_fdset_overlap (const struct GNUNET_NETWORK_FDSet *fds1,
 570                               const struct GNUNET_NETWORK_FDSet *fds2);
 571
 572
 573 /**
 574  * Creates an fd set
 575  *
 576  * @return a new fd set
 577  */
 578 struct GNUNET_NETWORK_FDSet *
 579 GNUNET_NETWORK_fdset_create (void);
 580
 581
 582 /**
 583  * Releases the associated memory of an fd set
 584  *
 585  * @param fds fd set
 586  */
 587 void
 588 GNUNET_NETWORK_fdset_destroy (struct GNUNET_NETWORK_FDSet *fds);
 589
 590
 591 /**
 592  * Test if the given @a port is available.
 593  *
 594  * @param ipproto transport protocol to test (i.e. IPPROTO_TCP)
 595  * @param port port number to test
 596  * @return #GNUNET_OK if the port is available, #GNUNET_NO if not
 597  */
 598 int
 599 GNUNET_NETWORK_test_port_free (int ipproto,
 600                                uint16_t port);
 601
 602
 603 #if 0                           /* keep Emacsens' auto-indent happy */
 604 {
 605 #endif
 606 #ifdef __cplusplus
 607 }
 608 #endif
 609
 610 #endif /* GNUNET_NETWORK_LIB_H */
 611
 612 /** @} */  /* end of group */