2 This file is part of GNUnet.
3 Copyright (C) 2009-2013 GNUnet e.V.
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.
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.
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/>.
18 SPDX-License-Identifier: AGPL3.0-or-later
25 * Basic low-level networking interface
27 * @defgroup network Network library
28 * Basic low-level networking interface
31 #ifndef GNUNET_NETWORK_LIB_H
32 #define GNUNET_NETWORK_LIB_H
37 #if 0 /* keep Emacsens' auto-indent happy */
42 #ifdef HAVE_SYS_SOCKET_H
43 #include <sys/socket.h>
50 * @brief handle to a socket
52 struct GNUNET_NETWORK_Handle;
56 * @brief collection of IO descriptors
58 struct GNUNET_NETWORK_FDSet
61 * Maximum number of any socket descriptor in the set (plus one)
66 * Bitset with the descriptors.
72 #include "gnunet_disk_lib.h"
73 #include "gnunet_time_lib.h"
76 * Test if the given protocol family is supported by this system.
78 * @param pf protocol family to test (PF_INET, PF_INET6, PF_UNIX)
79 * @return #GNUNET_OK if the PF is supported
82 GNUNET_NETWORK_test_pf (int pf);
86 * Given a unixpath that is too long (larger than UNIX_PATH_MAX),
87 * shorten it to an acceptable length while keeping it unique
88 * and making sure it remains a valid filename (if possible).
90 * @param unixpath long path, will be freed (or same pointer returned
91 * with moved 0-termination).
92 * @return shortened unixpath, NULL on error
95 GNUNET_NETWORK_shorten_unixpath (char *unixpath);
99 * If services crash, they can leave a unix domain socket file on the
100 * disk. This needs to be manually removed, because otherwise both
101 * bind() and connect() for the respective address will fail. In this
102 * function, we test if such a left-over file exists, and if so,
103 * remove it (unless there is a listening service at the address).
105 * @param un unix domain socket address to check
108 GNUNET_NETWORK_unix_precheck (const struct sockaddr_un *un);
112 * Accept a new connection on a socket. Configure it for non-blocking
113 * IO and mark it as non-inheritable to child processes (set the
114 * close-on-exec flag).
116 * @param desc bound socket
117 * @param address address of the connecting peer, may be NULL
118 * @param address_len length of address
119 * @return client socket
121 struct GNUNET_NETWORK_Handle *
122 GNUNET_NETWORK_socket_accept (const struct GNUNET_NETWORK_Handle *desc,
123 struct sockaddr *address,
124 socklen_t *address_len);
128 * Box a native socket (and check that it is a socket).
130 * @param fd socket to box
131 * @return NULL on error (including not supported on target platform)
133 struct GNUNET_NETWORK_Handle *
134 GNUNET_NETWORK_socket_box_native (int fd);
138 * Set if a socket should use blocking or non-blocking IO.
141 * @param doBlock blocking mode
142 * @return #GNUNET_OK on success, #GNUNET_SYSERR on error
145 GNUNET_NETWORK_socket_set_blocking (struct GNUNET_NETWORK_Handle *fd,
150 * Bind a socket to a particular address.
152 * @param desc socket to bind
153 * @param address address to be bound
154 * @param address_len length of @a address
155 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
158 GNUNET_NETWORK_socket_bind (struct GNUNET_NETWORK_Handle *desc,
159 const struct sockaddr *address,
160 socklen_t address_len);
165 * @param desc socket to close
166 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
169 GNUNET_NETWORK_socket_close (struct GNUNET_NETWORK_Handle *desc);
173 * Only free memory of a socket, keep the file descriptor untouched.
178 GNUNET_NETWORK_socket_free_memory_only_ (struct GNUNET_NETWORK_Handle *desc);
182 * Connect a socket to some remote address.
184 * @param desc socket to connect
185 * @param address peer address
186 * @param address_len of @a address
187 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
190 GNUNET_NETWORK_socket_connect (const struct GNUNET_NETWORK_Handle *desc,
191 const struct sockaddr *address,
192 socklen_t address_len);
198 * @param desc socket to inspect
199 * @param level protocol level of the option
200 * @param optname identifier of the option
201 * @param optval options
202 * @param optlen length of optval
203 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
206 GNUNET_NETWORK_socket_getsockopt (const struct GNUNET_NETWORK_Handle *desc,
216 * @param desc socket to start listening on
217 * @param backlog length of the listen queue
218 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
221 GNUNET_NETWORK_socket_listen (const struct GNUNET_NETWORK_Handle *desc,
226 * How much data is available to be read on this descriptor?
229 * @returns #GNUNET_SYSERR if no data is available, or on error!
232 GNUNET_NETWORK_socket_recvfrom_amount (const struct
233 GNUNET_NETWORK_Handle *desc);
237 * Read data from a socket (always non-blocking).
240 * @param buffer buffer
241 * @param length length of buffer
242 * @param src_addr either the source to recv from, or all zeroes
243 * to be filled in by recvfrom
244 * @param addrlen length of the addr
247 GNUNET_NETWORK_socket_recvfrom (const struct GNUNET_NETWORK_Handle *desc,
250 struct sockaddr *src_addr,
255 * Read data from a connected socket (always non-blocking).
258 * @param buffer buffer
259 * @param length length of buffer
260 * @return number of bytes read
263 GNUNET_NETWORK_socket_recv (const struct GNUNET_NETWORK_Handle *desc,
269 * Check if sockets meet certain conditions.
271 * @param rfds set of sockets to be checked for readability
272 * @param wfds set of sockets to be checked for writability
273 * @param efds set of sockets to be checked for exceptions
274 * @param timeout relative value when to return
275 * @return number of selected sockets, #GNUNET_SYSERR on error
278 GNUNET_NETWORK_socket_select (struct GNUNET_NETWORK_FDSet *rfds,
279 struct GNUNET_NETWORK_FDSet *wfds,
280 struct GNUNET_NETWORK_FDSet *efds,
281 struct GNUNET_TIME_Relative timeout);
285 * Send data (always non-blocking).
288 * @param buffer data to send
289 * @param length size of the buffer
290 * @return number of bytes sent, #GNUNET_SYSERR on error
293 GNUNET_NETWORK_socket_send (const struct GNUNET_NETWORK_Handle *desc,
299 * Send data to a particular destination (always non-blocking).
300 * This function only works for UDP sockets.
303 * @param message data to send
304 * @param length size of the data in @a message
305 * @param dest_addr destination address
306 * @param dest_len length of @a dest_addr
307 * @return number of bytes sent, #GNUNET_SYSERR on error
310 GNUNET_NETWORK_socket_sendto (const struct GNUNET_NETWORK_Handle *desc,
313 const struct sockaddr *dest_addr,
321 * @param level protocol level of the option
322 * @param option_name option identifier
323 * @param option_value value to set
324 * @param option_len size of @a option_value
325 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
328 GNUNET_NETWORK_socket_setsockopt (struct GNUNET_NETWORK_Handle *fd,
331 const void *option_value,
332 socklen_t option_len);
336 * Shut down socket operations
339 * @param how type of shutdown
340 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
343 GNUNET_NETWORK_socket_shutdown (struct GNUNET_NETWORK_Handle *desc,
348 * Disable the "CORK" feature for communication with the given socket,
349 * forcing the OS to immediately flush the buffer on transmission
350 * instead of potentially buffering multiple messages. Essentially
351 * reduces the OS send buffers to zero.
354 * @return #GNUNET_OK on success, #GNUNET_SYSERR otherwise
357 GNUNET_NETWORK_socket_disable_corking (struct GNUNET_NETWORK_Handle *desc);
361 * Create a new socket. Configure it for non-blocking IO and
362 * mark it as non-inheritable to child processes (set the
363 * close-on-exec flag).
365 * @param domain domain of the socket
366 * @param type socket type
367 * @param protocol network protocol
368 * @return new socket, NULL on error
370 struct GNUNET_NETWORK_Handle *
371 GNUNET_NETWORK_socket_create (int domain,
377 * Reset FD set (clears all file descriptors).
379 * @param fds fd set to clear
382 GNUNET_NETWORK_fdset_zero (struct GNUNET_NETWORK_FDSet *fds);
386 * Add a socket to the FD set
389 * @param desc socket to add
392 GNUNET_NETWORK_fdset_set (struct GNUNET_NETWORK_FDSet *fds,
393 const struct GNUNET_NETWORK_Handle *desc);
397 * Check whether a socket is part of the fd set
401 * @return #GNUNET_YES if the socket is in the set
404 GNUNET_NETWORK_fdset_isset (const struct GNUNET_NETWORK_FDSet *fds,
405 const struct GNUNET_NETWORK_Handle *desc);
409 * Add one fd set to another (computes the union).
411 * @param dst the fd set to add to
412 * @param src the fd set to add from
415 GNUNET_NETWORK_fdset_add (struct GNUNET_NETWORK_FDSet *dst,
416 const struct GNUNET_NETWORK_FDSet *src);
420 * Copy one fd set to another
422 * @param to destination
426 GNUNET_NETWORK_fdset_copy (struct GNUNET_NETWORK_FDSet *to,
427 const struct GNUNET_NETWORK_FDSet *from);
431 * Return file descriptor for this network handle
433 * @param desc wrapper to process
434 * @return POSIX file descriptor
437 GNUNET_NETWORK_get_fd (const struct GNUNET_NETWORK_Handle *desc);
441 * Return the sockaddr for this network handle
443 * @param desc wrapper to process
444 * @return POSIX file descriptor
447 GNUNET_NETWORK_get_addr (const struct GNUNET_NETWORK_Handle *desc);
451 * Return sockaddr length for this network handle
453 * @param desc wrapper to process
454 * @return socklen_t for sockaddr
457 GNUNET_NETWORK_get_addrlen (const struct GNUNET_NETWORK_Handle *desc);
461 * Copy a native fd set into the GNUnet representation.
463 * @param to destination
464 * @param from native source set
465 * @param nfds the biggest socket number in from + 1
468 GNUNET_NETWORK_fdset_copy_native (struct GNUNET_NETWORK_FDSet *to,
474 * Set a native fd in a set
476 * @param to destination
477 * @param nfd native FD to set
480 GNUNET_NETWORK_fdset_set_native (struct GNUNET_NETWORK_FDSet *to,
485 * Test native fd in a set
487 * @param to set to test, NULL for empty set
488 * @param nfd native FD to test, -1 for none
489 * @return #GNUNET_YES if to contains nfd
492 GNUNET_NETWORK_fdset_test_native (const struct GNUNET_NETWORK_FDSet *to,
497 * Add a file handle to the fd set
500 * @param h the file handle to add
503 GNUNET_NETWORK_fdset_handle_set (struct GNUNET_NETWORK_FDSet *fds,
504 const struct GNUNET_DISK_FileHandle *h);
508 * Add a file handle to the fd set
509 * On W32: ensure that the handle is first in the array.
512 * @param h the file handle to add
515 GNUNET_NETWORK_fdset_handle_set_first (struct GNUNET_NETWORK_FDSet *fds,
516 const struct GNUNET_DISK_FileHandle *h);
520 * Check if a file handle is part of an fd set
523 * @param h file handle
524 * @return #GNUNET_YES if the file handle is part of the set
527 GNUNET_NETWORK_fdset_handle_isset (const struct GNUNET_NETWORK_FDSet *fds,
528 const struct GNUNET_DISK_FileHandle *h);
532 * Checks if two fd sets overlap
534 * @param fds1 first fd set
535 * @param fds2 second fd set
536 * @return #GNUNET_YES if they do overlap, #GNUNET_NO otherwise
539 GNUNET_NETWORK_fdset_overlap (const struct GNUNET_NETWORK_FDSet *fds1,
540 const struct GNUNET_NETWORK_FDSet *fds2);
546 * @return a new fd set
548 struct GNUNET_NETWORK_FDSet *
549 GNUNET_NETWORK_fdset_create (void);
553 * Releases the associated memory of an fd set
558 GNUNET_NETWORK_fdset_destroy (struct GNUNET_NETWORK_FDSet *fds);
562 * Test if the given @a port is available.
564 * @param ipproto transport protocol to test (i.e. IPPROTO_TCP)
565 * @param port port number to test
566 * @return #GNUNET_OK if the port is available, #GNUNET_NO if not
569 GNUNET_NETWORK_test_port_free (int ipproto,
573 #if 0 /* keep Emacsens' auto-indent happy */
580 #endif /* GNUNET_NETWORK_LIB_H */
582 /** @} */ /* end of group */