gnunet_common.h (58097B)
1 /* 2 This file is part of GNUnet. 3 Copyright (C) 2006-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 * @file include/gnunet_common.h 27 * @brief commonly used definitions; globals in this file 28 * are exempt from the rule that the module name ("common") 29 * must be part of the symbol name. 30 * 31 * @author Christian Grothoff 32 * @author Nils Durner 33 * @author Martin Schanzenbach 34 * 35 * @defgroup logging Logging 36 * @see [Documentation](https://gnunet.org/logging) 37 * 38 * @defgroup memory Memory management 39 */ 40 #ifndef GNUNET_COMMON_H 41 #define GNUNET_COMMON_H 42 43 #include "gnunet_config.h" 44 45 #include <stdbool.h> 46 #include <stdlib.h> 47 #include <sys/socket.h> 48 #include <sys/un.h> 49 #include <netinet/in.h> 50 #include <arpa/inet.h> 51 #include <stdint.h> 52 #include <stdarg.h> 53 #include <sys/types.h> 54 55 #if defined(__FreeBSD__) 56 57 #include <sys/endian.h> 58 #define bswap_16(x) bswap16 (x) 59 #define bswap_32(x) bswap32 (x) 60 #define bswap_64(x) bswap64 (x) 61 62 #elif defined(__OpenBSD__) 63 64 #define bswap_16(x) swap16 (x) 65 #define bswap_32(x) swap32 (x) 66 #define bswap_64(x) swap64 (x) 67 68 #elif defined(__NetBSD__) 69 70 #include <machine/bswap.h> 71 #if defined(__BSWAP_RENAME) && ! defined(__bswap_32) 72 #define bswap_16(x) bswap16 (x) 73 #define bswap_32(x) bswap32 (x) 74 #define bswap_64(x) bswap64 (x) 75 #endif 76 77 #elif defined(__linux__) || defined(GNU) 78 #include <byteswap.h> 79 #endif 80 81 82 /* This is also included in platform.h, but over there a couple of 83 GNUnet-specific gettext-related macros are defined in addition to including 84 the header file. Because this header file uses gettext, this include 85 statement makes sure gettext macros are defined even when platform.h is 86 unavailable. */ 87 #ifndef _LIBGETTEXT_H 88 #include "gettext.h" 89 #endif 90 91 #ifdef __cplusplus 92 extern "C" { 93 #if 0 /* keep Emacsens' auto-indent happy */ 94 } 95 #endif 96 #endif 97 98 /** 99 * Version of the API (for entire gnunetutil.so library). 100 */ 101 #define GNUNET_UTIL_VERSION 0x000A0104 102 103 104 /** 105 * Named constants for return values. The following invariants hold: 106 * `GNUNET_NO == 0` (to allow `if (GNUNET_NO)`) `GNUNET_OK != 107 * GNUNET_SYSERR`, `GNUNET_OK != GNUNET_NO`, `GNUNET_NO != 108 * GNUNET_SYSERR` and finally `GNUNET_YES != GNUNET_NO`. 109 */ 110 enum GNUNET_GenericReturnValue 111 { 112 GNUNET_SYSERR = -1, 113 GNUNET_NO = 0, 114 GNUNET_OK = 1, 115 /* intentionally identical to #GNUNET_OK! */ 116 GNUNET_YES = 1, 117 }; 118 119 120 #define GNUNET_MIN(a, b) (((a) < (b)) ? (a) : (b)) 121 122 #define GNUNET_MAX(a, b) (((a) > (b)) ? (a) : (b)) 123 124 /* some systems use one underscore only, and mingw uses no underscore... */ 125 #ifndef __BYTE_ORDER 126 #ifdef _BYTE_ORDER 127 #define __BYTE_ORDER _BYTE_ORDER 128 #else 129 #ifdef BYTE_ORDER 130 #define __BYTE_ORDER BYTE_ORDER 131 #endif 132 #endif 133 #endif 134 #ifndef __BIG_ENDIAN 135 #ifdef _BIG_ENDIAN 136 #define __BIG_ENDIAN _BIG_ENDIAN 137 #else 138 #ifdef BIG_ENDIAN 139 #define __BIG_ENDIAN BIG_ENDIAN 140 #endif 141 #endif 142 #endif 143 #ifndef __LITTLE_ENDIAN 144 #ifdef _LITTLE_ENDIAN 145 #define __LITTLE_ENDIAN _LITTLE_ENDIAN 146 #else 147 #ifdef LITTLE_ENDIAN 148 #define __LITTLE_ENDIAN LITTLE_ENDIAN 149 #endif 150 #endif 151 #endif 152 153 /** 154 * @ingroup logging 155 * define #GNUNET_EXTRA_LOGGING if using this header outside the GNUnet source 156 * tree where gnunet_config.h is unavailable 157 */ 158 #ifndef GNUNET_EXTRA_LOGGING 159 #define GNUNET_EXTRA_LOGGING 1 160 #endif 161 162 /** 163 * Endian operations 164 */ 165 166 #if defined(bswap_16) || defined(bswap_32) || defined(bswap_64) 167 #define BYTE_SWAP_16(x) bswap_16 (x) 168 #define BYTE_SWAP_32(x) bswap_32 (x) 169 #define BYTE_SWAP_64(x) bswap_64 (x) 170 #else 171 #define BYTE_SWAP_16(x) ((((x) & 0x00ff) << 8) | (((x) & 0xff00) >> 8)) 172 173 #define BYTE_SWAP_32(x) \ 174 ((((x) & 0x000000ffU) << 24) | (((x) & 0x0000ff00U) << 8) \ 175 | (((x) & 0x00ff0000U) >> 8) | (((x) & 0xff000000U) >> 24)) 176 177 #define BYTE_SWAP_64(x) \ 178 ((((x) & 0x00000000000000ffUL) << 56) | (((x) & 0x000000000000ff00UL) << \ 179 40) \ 180 | (((x) & 0x0000000000ff0000UL) << 24) | (((x) & 0x00000000ff000000UL) \ 181 << 8) \ 182 | (((x) & 0x000000ff00000000UL) >> 8) | (((x) & 0x0000ff0000000000UL) \ 183 >> 24) \ 184 | (((x) & 0x00ff000000000000UL) >> 40) | (((x) & 0xff00000000000000UL) \ 185 >> \ 186 56)) 187 #endif 188 189 #if __BYTE_ORDER == __LITTLE_ENDIAN 190 #define GNUNET_htobe16(x) BYTE_SWAP_16 (x) 191 #define GNUNET_htole16(x) (x) 192 #define GNUNET_be16toh(x) BYTE_SWAP_16 (x) 193 #define GNUNET_le16toh(x) (x) 194 195 #define GNUNET_htobe32(x) BYTE_SWAP_32 (x) 196 #define GNUNET_htole32(x) (x) 197 #define GNUNET_be32toh(x) BYTE_SWAP_32 (x) 198 #define GNUNET_le32toh(x) (x) 199 200 #define GNUNET_htobe64(x) BYTE_SWAP_64 (x) 201 #define GNUNET_htole64(x) (x) 202 #define GNUNET_be64toh(x) BYTE_SWAP_64 (x) 203 #define GNUNET_le64toh(x) (x) 204 #endif 205 #if __BYTE_ORDER == __BIG_ENDIAN 206 #define GNUNET_htobe16(x) (x) 207 #define GNUNET_htole16(x) BYTE_SWAP_16 (x) 208 #define GNUNET_be16toh(x) (x) 209 #define GNUNET_le16toh(x) BYTE_SWAP_16 (x) 210 211 #define GNUNET_htobe32(x) (x) 212 #define GNUNET_htole32(x) BYTE_SWAP_32 (x) 213 #define GNUNET_be32toh(x) (x) 214 #define GNUNET_le32toh(x) BYTE_SWAP_32 (x) 215 216 #define GNUNET_htobe64(x) (x) 217 #define GNUNET_htole64(x) BYTE_SWAP_64 (x) 218 #define GNUNET_be64toh(x) (x) 219 #define GNUNET_le64toh(x) BYTE_SWAP_64 (x) 220 #endif 221 222 223 /** 224 * Macro used to avoid using 0 for the length of a variable-size 225 * array (Non-Zero-Length). 226 * 227 * Basically, C standard says that "int[n] x;" is undefined if n=0. 228 * This was supposed to prevent issues with pointer aliasing. 229 * However, C compilers may conclude that n!=0 as n=0 would be 230 * undefined, and then optimize under the assumption n!=0, which 231 * could cause actual issues. Hence, when initializing an array 232 * on the stack with a variable-length that might be zero, write 233 * "int[GNUNET_NZL(n)] x;" instead of "int[n] x". 234 */ 235 #define GNUNET_NZL(l) GNUNET_MAX (1, l) 236 237 238 /** 239 * gcc-ism to get packed structs. 240 */ 241 #define GNUNET_PACKED __attribute__ ((packed)) 242 243 /** 244 * gcc-ism to get gcc bitfield layout when compiling with -mms-bitfields 245 */ 246 #define GNUNET_GCC_STRUCT_LAYOUT 247 248 /** 249 * gcc-ism to force alignment; we use this to align char-arrays 250 * that may then be cast to 'struct's. See also gcc 251 * bug #33594. 252 */ 253 #ifdef __BIGGEST_ALIGNMENT__ 254 #define GNUNET_ALIGN __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))) 255 #else 256 #define GNUNET_ALIGN __attribute__ ((aligned (8))) 257 #endif 258 259 /** 260 * gcc-ism to document unused arguments 261 */ 262 #define GNUNET_UNUSED __attribute__ ((unused)) 263 264 /** 265 * gcc-ism to document functions that don't return 266 */ 267 #define GNUNET_NORETURN __attribute__ ((noreturn)) 268 269 /** 270 * Define as empty, GNUNET_PACKED should suffice, but this won't work on W32 271 */ 272 #define GNUNET_NETWORK_STRUCT_BEGIN 273 274 /** 275 * Define as empty, GNUNET_PACKED should suffice, but this won't work on W32; 276 */ 277 #define GNUNET_NETWORK_STRUCT_END 278 279 /* ************************ super-general types *********************** */ 280 281 GNUNET_NETWORK_STRUCT_BEGIN 282 283 /** 284 * @brief A 512-bit hashcode. These are the default length for GNUnet, using SHA-512. 285 */ 286 struct GNUNET_HashCode 287 { 288 uint32_t bits[512 / 8 / sizeof(uint32_t)]; /* = 16 */ 289 }; 290 291 292 /** 293 * @brief A 256-bit hashcode. Used under special conditions, like when space 294 * is critical and security is not impacted by it. 295 */ 296 struct GNUNET_ShortHashCode 297 { 298 uint32_t bits[256 / 8 / sizeof(uint32_t)]; /* = 8 */ 299 }; 300 301 302 /** 303 * A UUID, a 128 bit "random" value. We OFTEN use 304 * timeflakes (see: https://github.com/anthonynsimon/timeflake), 305 * where only 80 bits are random and the rest encodes 306 * a timestamp to improve database access. 307 * 308 * See #GNUNET_CRYPTO_random_timeflake(). 309 */ 310 struct GNUNET_Uuid 311 { 312 /** 313 * 128 random bits. 314 */ 315 uint32_t value[4]; 316 }; 317 318 319 /** 320 * Header for all communications. 321 */ 322 struct GNUNET_MessageHeader 323 { 324 /** 325 * The length of the struct (in bytes, including the length field itself), 326 * in big-endian format. 327 */ 328 uint16_t size GNUNET_PACKED; 329 330 /** 331 * The type of the message (GNUNET_MESSAGE_TYPE_XXXX), in big-endian format. 332 */ 333 uint16_t type GNUNET_PACKED; 334 }; 335 336 337 /** 338 * Identifier for an asynchronous execution context. 339 */ 340 struct GNUNET_AsyncScopeId 341 { 342 uint32_t bits[16 / sizeof(uint32_t)]; /* = 16 bytes */ 343 }; 344 345 GNUNET_NETWORK_STRUCT_END 346 347 348 /** 349 * Saved async scope identifier or root scope. 350 */ 351 struct GNUNET_AsyncScopeSave 352 { 353 /** 354 * Saved scope. Unused if 'have_scope==GNUNET_NO'. 355 */ 356 struct GNUNET_AsyncScopeId scope_id; 357 358 /** 359 * GNUNET_YES unless this saved scope is the unnamed root scope. 360 */ 361 int have_scope; 362 }; 363 364 365 /** 366 * Function called with a filename. 367 * 368 * @param cls closure 369 * @param filename complete filename (absolute path) 370 * @return #GNUNET_OK to continue to iterate, 371 * #GNUNET_NO to stop iteration with no error, 372 * #GNUNET_SYSERR to abort iteration with error! 373 */ 374 typedef enum GNUNET_GenericReturnValue 375 (*GNUNET_FileNameCallback) (void *cls, 376 const char *filename); 377 378 379 /** 380 * Generic continuation callback. 381 * 382 * @param cls Closure. 383 */ 384 typedef void 385 (*GNUNET_ContinuationCallback) (void *cls); 386 387 388 /** 389 * Function called with the result of an asynchronous operation. 390 * 391 * @param cls 392 * Closure. 393 * @param result_code 394 * Result code for the operation. 395 * @param data 396 * Data result for the operation. 397 * @param data_size 398 * Size of @a data. 399 */ 400 typedef void 401 (*GNUNET_ResultCallback) (void *cls, 402 int64_t result_code, 403 const void *data, 404 uint16_t data_size); 405 406 407 /* ****************************** logging ***************************** */ 408 409 /** 410 * @ingroup logging 411 * Types of errors. 412 */ 413 enum GNUNET_ErrorType 414 { 415 GNUNET_ERROR_TYPE_UNSPECIFIED = -1, 416 GNUNET_ERROR_TYPE_NONE = 0, 417 GNUNET_ERROR_TYPE_ERROR = 1, 418 GNUNET_ERROR_TYPE_WARNING = 2, 419 /* UX: We need a message type that is output by 420 * default without looking like there is a problem. 421 */ 422 GNUNET_ERROR_TYPE_MESSAGE = 4, 423 GNUNET_ERROR_TYPE_INFO = 8, 424 GNUNET_ERROR_TYPE_DEBUG = 16, 425 GNUNET_ERROR_TYPE_INVALID = 32, 426 GNUNET_ERROR_TYPE_BULK = 64 427 }; 428 429 430 /** 431 * @ingroup logging 432 * User-defined handler for log messages. 433 * 434 * @param cls closure 435 * @param kind severeity 436 * @param component what component is issuing the message? 437 * @param date when was the message logged? 438 * @param message what is the message 439 */ 440 typedef void 441 (*GNUNET_Logger) (void *cls, 442 enum GNUNET_ErrorType kind, 443 const char *component, 444 const char *date, 445 const char *message); 446 447 448 /** 449 * @ingroup logging 450 * Get the number of log calls that are going to be skipped 451 * 452 * @return number of log calls to be ignored 453 */ 454 int 455 GNUNET_get_log_skip (void); 456 457 458 #if ! defined(GNUNET_CULL_LOGGING) 459 int 460 GNUNET_get_log_call_status (int caller_level, 461 const char *comp, 462 const char *file, 463 const char *function, 464 int line); 465 466 #endif 467 468 /* *INDENT-OFF* */ 469 /** 470 * @ingroup logging 471 * Main log function. 472 * 473 * @param kind how serious is the error? 474 * @param message what is the message (format string) 475 * @param ... arguments for format string 476 */ 477 void 478 GNUNET_log_nocheck (enum GNUNET_ErrorType kind, 479 const char *message, 480 ...) 481 __attribute__ ((format (printf, 2, 3))); 482 483 /* from glib */ 484 #if defined(__GNUC__) && (__GNUC__ > 2) && defined(__OPTIMIZE__) 485 #define _GNUNET_BOOLEAN_EXPR(expr) \ 486 __extension__ ({ \ 487 int _gnunet_boolean_var_; \ 488 if (expr) \ 489 _gnunet_boolean_var_ = 1; \ 490 else \ 491 _gnunet_boolean_var_ = 0; \ 492 _gnunet_boolean_var_; \ 493 }) 494 #define GN_LIKELY(expr) (__builtin_expect (_GNUNET_BOOLEAN_EXPR (expr), 1)) 495 #define GN_UNLIKELY(expr) (__builtin_expect (_GNUNET_BOOLEAN_EXPR (expr), 0)) 496 #else 497 #define GN_LIKELY(expr) (expr) 498 #define GN_UNLIKELY(expr) (expr) 499 #endif 500 501 #if ! defined(GNUNET_LOG_CALL_STATUS) 502 #define GNUNET_LOG_CALL_STATUS -1 503 #endif 504 /* *INDENT-ON* */ 505 506 507 /** 508 * @ingroup logging 509 * Log function that specifies an alternative component. 510 * This function should be used by plugins. 511 * 512 * @param kind how serious is the error? 513 * @param comp component responsible for generating the message 514 * @param message what is the message (format string) 515 * @param ... arguments for format string 516 */ 517 void 518 GNUNET_log_from_nocheck (enum GNUNET_ErrorType kind, 519 const char *comp, 520 const char *message, 521 ...) 522 __attribute__ ((format (printf, 3, 4))); 523 524 #if ! defined(GNUNET_CULL_LOGGING) 525 #define GNUNET_log_from(kind, comp, ...) \ 526 do \ 527 { \ 528 static int log_call_enabled = GNUNET_LOG_CALL_STATUS; \ 529 if ((GNUNET_EXTRA_LOGGING > 0) || \ 530 ((GNUNET_ERROR_TYPE_DEBUG & (kind)) == 0)) \ 531 { \ 532 if (GN_UNLIKELY (log_call_enabled == -1)) \ 533 log_call_enabled = \ 534 GNUNET_get_log_call_status ((kind) & (~GNUNET_ERROR_TYPE_BULK), \ 535 (comp), \ 536 __FILE__, \ 537 __func__, \ 538 __LINE__); \ 539 if (GN_UNLIKELY (GNUNET_get_log_skip () > 0)) \ 540 { \ 541 GNUNET_log_skip (-1, GNUNET_NO); \ 542 } \ 543 else \ 544 { \ 545 if (GN_UNLIKELY (log_call_enabled)) \ 546 GNUNET_log_from_nocheck ((kind), comp, __VA_ARGS__); \ 547 } \ 548 } \ 549 } while (0) 550 551 #define GNUNET_log(kind, ...) \ 552 do \ 553 { \ 554 static int log_call_enabled = GNUNET_LOG_CALL_STATUS; \ 555 if ((GNUNET_EXTRA_LOGGING > 0) || \ 556 ((GNUNET_ERROR_TYPE_DEBUG & (kind)) == 0)) \ 557 { \ 558 if (GN_UNLIKELY (log_call_enabled == -1)) \ 559 log_call_enabled = \ 560 GNUNET_get_log_call_status ((kind) & (~GNUNET_ERROR_TYPE_BULK), \ 561 NULL, \ 562 __FILE__, \ 563 __func__, \ 564 __LINE__); \ 565 if (GN_UNLIKELY (GNUNET_get_log_skip () > 0)) \ 566 { \ 567 GNUNET_log_skip (-1, GNUNET_NO); \ 568 } \ 569 else \ 570 { \ 571 if (GN_UNLIKELY (log_call_enabled)) \ 572 GNUNET_log_nocheck ((kind), __VA_ARGS__); \ 573 } \ 574 } \ 575 } while (0) 576 #else 577 #define GNUNET_log(...) 578 #define GNUNET_log_from(...) 579 #endif 580 581 582 /** 583 * @ingroup logging 584 * Log error message about missing configuration option. 585 * 586 * @param kind log level 587 * @param section section with missing option 588 * @param option name of missing option 589 */ 590 void 591 GNUNET_log_config_missing (enum GNUNET_ErrorType kind, 592 const char *section, 593 const char *option); 594 595 596 /** 597 * @ingroup logging 598 * Log error message about invalid configuration option value. 599 * 600 * @param kind log level 601 * @param section section with invalid option 602 * @param option name of invalid option 603 * @param required what is required that is invalid about the option 604 */ 605 void 606 GNUNET_log_config_invalid (enum GNUNET_ErrorType kind, 607 const char *section, 608 const char *option, 609 const char *required); 610 611 612 /** 613 * @ingroup logging 614 * Abort the process, generate a core dump if possible. 615 * Most code should use `GNUNET_assert (0)` instead to 616 * first log the location of the failure. 617 */ 618 void 619 GNUNET_abort_ (void) GNUNET_NORETURN; 620 621 622 /** 623 * Convert a buffer to an 8-character string 624 * representative of the contents. This is used 625 * for logging binary data when debugging. 626 * 627 * @param buf buffer to log 628 * @param buf_size number of bytes in @a buf 629 * @return text representation of buf, valid until next 630 * call to this function 631 */ 632 const char * 633 GNUNET_b2s (const void *buf, 634 size_t buf_size); 635 636 637 /** 638 * Convert a fixed-sized object to a string using 639 * #GNUNET_b2s(). 640 * 641 * @param obj address of object to convert 642 * @return string representing the binary obj buffer 643 */ 644 #define GNUNET_B2S(obj) GNUNET_b2s ((obj), sizeof (*(obj))) 645 646 647 /** 648 * @ingroup logging 649 * Ignore the next @a n calls to the log function. 650 * 651 * @param n number of log calls to ignore (could be negative) 652 * @param check_reset #GNUNET_YES to assert that the log skip counter is currently zero 653 */ 654 void 655 GNUNET_log_skip (int n, int check_reset); 656 657 658 /** 659 * @ingroup logging 660 * Setup logging. 661 * 662 * @param comp default component to use 663 * @param loglevel what types of messages should be logged 664 * @param logfile change logging to logfile (use NULL to keep stderr) 665 * @return #GNUNET_OK on success, #GNUNET_SYSERR if logfile could not be opened 666 */ 667 enum GNUNET_GenericReturnValue 668 GNUNET_log_setup (const char *comp, 669 const char *loglevel, 670 const char *logfile); 671 672 673 /** 674 * @ingroup logging 675 * Add a custom logger. Note that installing any custom logger 676 * will disable the standard logger. When multiple custom loggers 677 * are installed, all will be called. The standard logger will 678 * only be used if no custom loggers are present. 679 * 680 * @param logger log function 681 * @param logger_cls closure for @a logger 682 */ 683 void 684 GNUNET_logger_add (GNUNET_Logger logger, 685 void *logger_cls); 686 687 688 /** 689 * @ingroup logging 690 * Remove a custom logger. 691 * 692 * @param logger log function 693 * @param logger_cls closure for @a logger 694 */ 695 void 696 GNUNET_logger_remove (GNUNET_Logger logger, 697 void *logger_cls); 698 699 700 /** 701 * @ingroup logging 702 * Convert a short hash value to a string (for printing debug messages). 703 * This is one of the very few calls in the entire API that is 704 * NOT reentrant! 705 * 706 * @param shc the hash code 707 * @return string 708 */ 709 const char * 710 GNUNET_sh2s (const struct GNUNET_ShortHashCode *shc); 711 712 713 /** 714 * @ingroup logging 715 * Convert a UUID to a string (for printing debug messages). 716 * This is one of the very few calls in the entire API that is 717 * NOT reentrant! 718 * 719 * @param uuid the UUID 720 * @return string 721 */ 722 const char * 723 GNUNET_uuid2s (const struct GNUNET_Uuid *uuid); 724 725 726 /** 727 * @ingroup logging 728 * Convert a hash value to a string (for printing debug messages). 729 * This is one of the very few calls in the entire API that is 730 * NOT reentrant! 731 * 732 * @param hc the hash code 733 * @return string 734 */ 735 const char * 736 GNUNET_h2s (const struct GNUNET_HashCode *hc); 737 738 739 /** 740 * @ingroup logging 741 * Convert a hash value to a string (for printing debug messages). 742 * This is one of the very few calls in the entire API that is 743 * NOT reentrant! Identical to #GNUNET_h2s(), except that another 744 * buffer is used so both #GNUNET_h2s() and #GNUNET_h2s2() can be 745 * used within the same log statement. 746 * 747 * @param hc the hash code 748 * @return string 749 */ 750 const char * 751 GNUNET_h2s2 (const struct GNUNET_HashCode *hc); 752 753 754 /** 755 * @ingroup logging 756 * Convert a hash value to a string (for printing debug messages). 757 * This prints all 104 characters of a hashcode! 758 * This is one of the very few calls in the entire API that is 759 * NOT reentrant! 760 * 761 * @param hc the hash code 762 * @return string 763 */ 764 const char * 765 GNUNET_h2s_full (const struct GNUNET_HashCode *hc); 766 767 768 /** 769 * Public key. Details in gnunet_util_crypto.h. 770 */ 771 struct GNUNET_CRYPTO_EddsaPublicKey; 772 773 774 /** 775 * Public key. Details in gnunet_util_crypto.h. 776 */ 777 struct GNUNET_CRYPTO_EcdhePublicKey; 778 779 780 /** 781 * @ingroup logging 782 * Convert a public key value to a string (for printing debug messages). 783 * This is one of the very few calls in the entire API that is 784 * NOT reentrant! 785 * 786 * @param hc the hash code 787 * @return string 788 */ 789 const char * 790 GNUNET_p2s (const struct GNUNET_CRYPTO_EddsaPublicKey *p); 791 792 793 /** 794 * @ingroup logging 795 * Convert a public key value to a string (for printing debug messages). 796 * This is one of the very few calls in the entire API that is 797 * NOT reentrant! 798 * 799 * @param hc the hash code 800 * @return string 801 */ 802 const char * 803 GNUNET_p2s2 (const struct GNUNET_CRYPTO_EddsaPublicKey *p); 804 805 806 /** 807 * @ingroup logging 808 * Convert a public key value to a string (for printing debug messages). 809 * This is one of the very few calls in the entire API that is 810 * NOT reentrant! 811 * 812 * @param hc the hash code 813 * @return string 814 */ 815 const char * 816 GNUNET_e2s (const struct GNUNET_CRYPTO_EcdhePublicKey *p); 817 818 819 /** 820 * @ingroup logging 821 * Convert a public key value to a string (for printing debug messages). 822 * This is one of the very few calls in the entire API that is 823 * NOT reentrant! 824 * 825 * @param hc the hash code 826 * @return string 827 */ 828 const char * 829 GNUNET_e2s2 (const struct GNUNET_CRYPTO_EcdhePublicKey *p); 830 831 832 /** 833 * Forward declaration to make compiler happy depending on include order. 834 */ 835 struct GNUNET_PeerIdentity; 836 837 838 /** 839 * @ingroup logging 840 * Convert a peer identity to a string (for printing debug messages). 841 * This is one of the very few calls in the entire API that is 842 * NOT reentrant! 843 * 844 * @param pid the peer identity 845 * @return string form of the pid; will be overwritten by next 846 * call to #GNUNET_i2s(). 847 */ 848 const char * 849 GNUNET_i2s (const struct GNUNET_PeerIdentity *pid); 850 851 852 /** 853 * @ingroup logging 854 * Convert a peer identity to a string (for printing debug messages). 855 * This is one of the very few calls in the entire API that is 856 * NOT reentrant! Identical to #GNUNET_i2s(), except that another 857 * buffer is used so both #GNUNET_i2s() and #GNUNET_i2s2() can be 858 * used within the same log statement. 859 * 860 * @param pid the peer identity 861 * @return string form of the pid; will be overwritten by next 862 * call to #GNUNET_i2s(). 863 */ 864 const char * 865 GNUNET_i2s2 (const struct GNUNET_PeerIdentity *pid); 866 867 868 /** 869 * @ingroup logging 870 * Convert a peer identity to a string (for printing debug messages). 871 * This is one of the very few calls in the entire API that is 872 * NOT reentrant! 873 * 874 * @param pid the peer identity 875 * @return string form of the pid; will be overwritten by next 876 * call to #GNUNET_i2s_full(). 877 */ 878 const char * 879 GNUNET_i2s_full (const struct GNUNET_PeerIdentity *pid); 880 881 882 /** 883 * @ingroup logging 884 * Convert a "struct sockaddr*" (IPv4 or IPv6 address) to a string 885 * (for printing debug messages). This is one of the very few calls 886 * in the entire API that is NOT reentrant! 887 * 888 * @param addr the address 889 * @param addrlen the length of the @a addr 890 * @return nicely formatted string for the address 891 * will be overwritten by next call to #GNUNET_a2s(). 892 */ 893 const char * 894 GNUNET_a2s (const struct sockaddr *addr, socklen_t addrlen); 895 896 /** 897 * @ingroup logging 898 * Parse an ascii-encoded hexadecimal string into the 899 * buffer. The buffer must be (strlen (src) / 2) bytes 900 * in length. 901 * 902 * @param src the string 903 * @param dst the destination buffer 904 * @param dst_len the length of the @a dst buffer 905 * @param invert read from @a src in inverted direction. 906 * @return number of bytes written. 907 */ 908 size_t 909 GNUNET_hex2b (const char *src, void *dst, size_t dstlen, int invert); 910 911 /** 912 * @ingroup logging 913 * Print a byte string in hexadecimal ascii notation 914 * 915 * @param buf the byte string 916 * @param buf_len the length of the @a buf buffer 917 * @param fold insert newline after this number of bytes 918 (0 for no folding) 919 * @param in_be Output byte string in NBO 920 */ 921 void 922 GNUNET_print_bytes (const void *buf, 923 size_t buf_len, 924 int fold, 925 int in_be); 926 927 /** 928 * @ingroup logging 929 * Convert error type to string. 930 * 931 * @param kind type to convert 932 * @return string corresponding to the type 933 */ 934 const char * 935 GNUNET_error_type_to_string (enum GNUNET_ErrorType kind); 936 937 938 /** 939 * @ingroup logging 940 * Use this for fatal errors that cannot be handled 941 */ 942 #if __GNUC__ >= 6 || __clang_major__ >= 6 943 #define GNUNET_assert(cond) \ 944 do \ 945 { \ 946 _Pragma("GCC diagnostic push") \ 947 _Pragma("GCC diagnostic ignored \"-Wtautological-compare\"") \ 948 if (! (cond)) \ 949 { \ 950 GNUNET_log (GNUNET_ERROR_TYPE_ERROR, \ 951 dgettext ("gnunet", "Assertion failed at %s:%d. Aborting.\n"), \ 952 __FILE__, \ 953 __LINE__); \ 954 GNUNET_abort_ (); \ 955 } \ 956 _Pragma("GCC diagnostic pop") \ 957 } while (0) 958 #else 959 /* older GCC/clangs do not support -Wtautological-compare */ 960 #define GNUNET_assert(cond) \ 961 do \ 962 { \ 963 if (! (cond)) \ 964 { \ 965 GNUNET_log (GNUNET_ERROR_TYPE_ERROR, \ 966 dgettext ("gnunet", \ 967 "Assertion failed at %s:%d. Aborting.\n"), \ 968 __FILE__, \ 969 __LINE__); \ 970 GNUNET_abort_ (); \ 971 } \ 972 } while (0) 973 #endif 974 975 /** 976 * @ingroup logging 977 * Use this for fatal errors that cannot be handled 978 */ 979 #define GNUNET_assert_at(cond, f, l) \ 980 do \ 981 { \ 982 if (! (cond)) \ 983 { \ 984 GNUNET_log (GNUNET_ERROR_TYPE_ERROR, \ 985 dgettext ("gnunet", \ 986 "Assertion failed at %s:%d. Aborting.\n"), \ 987 f, \ 988 l); \ 989 GNUNET_abort_ (); \ 990 } \ 991 } while (0) 992 993 994 /** 995 * @ingroup logging 996 * Use this for fatal errors that cannot be handled 997 * 998 * @param cond Condition to evaluate 999 * @param comp Component string to use for logging 1000 */ 1001 #define GNUNET_assert_from(cond, comp) \ 1002 do \ 1003 { \ 1004 if (! (cond)) \ 1005 { \ 1006 GNUNET_log_from (GNUNET_ERROR_TYPE_ERROR, \ 1007 comp, \ 1008 dgettext ("gnunet", \ 1009 "Assertion failed at %s:%d. Aborting.\n") \ 1010 , \ 1011 __FILE__, \ 1012 __LINE__); \ 1013 GNUNET_abort_ (); \ 1014 } \ 1015 } while (0) 1016 1017 1018 #ifdef _Static_assert 1019 /** 1020 * Assertion to be checked (if supported by C compiler) at 1021 * compile time, otherwise checked at runtime and resulting 1022 * in an abort() on failure. 1023 * 1024 * @param cond condition to test, 0 implies failure 1025 */ 1026 #define GNUNET_static_assert(cond) _Static_assert (cond, "") 1027 #else 1028 /** 1029 * Assertion to be checked (if supported by C compiler) at 1030 * compile time, otherwise checked at runtime and resulting 1031 * in an abort() on failure. This is the case where the 1032 * compiler does not support static assertions. 1033 * 1034 * @param cond condition to test, 0 implies failure 1035 */ 1036 #define GNUNET_static_assert(cond) GNUNET_assert (cond) 1037 #endif 1038 1039 1040 /** 1041 * @ingroup logging 1042 * Use this for internal assertion violations that are 1043 * not fatal (can be handled) but should not occur. 1044 */ 1045 #define GNUNET_break(cond) \ 1046 do \ 1047 { \ 1048 if (! (cond)) \ 1049 { \ 1050 GNUNET_log (GNUNET_ERROR_TYPE_ERROR, \ 1051 dgettext ("gnunet", "Assertion failed at %s:%d.\n"), \ 1052 __FILE__, \ 1053 __LINE__); \ 1054 } \ 1055 } while (0) 1056 1057 1058 /** 1059 * @ingroup logging 1060 * Use this for assertion violations caused by other 1061 * peers (i.e. protocol violations). We do not want to 1062 * confuse end-users (say, some other peer runs an 1063 * older, broken or incompatible GNUnet version), but 1064 * we still want to see these problems during 1065 * development and testing. "OP == other peer". 1066 */ 1067 #define GNUNET_break_op(cond) \ 1068 do \ 1069 { \ 1070 if (! (cond)) \ 1071 { \ 1072 GNUNET_log (GNUNET_ERROR_TYPE_WARNING | GNUNET_ERROR_TYPE_BULK, \ 1073 dgettext ("gnunet", \ 1074 "External protocol violation detected at %s:%d.\n"), \ 1075 __FILE__, \ 1076 __LINE__); \ 1077 } \ 1078 } while (0) 1079 1080 1081 /** 1082 * @ingroup logging 1083 * Log an error message at log-level 'level' that indicates 1084 * a failure of the command 'cmd' with the message given 1085 * by strerror(errno). 1086 */ 1087 #define GNUNET_log_strerror(level, cmd) \ 1088 do \ 1089 { \ 1090 GNUNET_log (level, \ 1091 dgettext ("gnunet", \ 1092 "`%s' failed at %s:%d with error: %s\n"), \ 1093 cmd, \ 1094 __FILE__, \ 1095 __LINE__, \ 1096 strerror (errno)); \ 1097 } while (0) 1098 1099 1100 /** 1101 * @ingroup logging 1102 * Log an error message at log-level 'level' that indicates 1103 * a failure of the command 'cmd' with the message given 1104 * by strerror(errno). 1105 */ 1106 #define GNUNET_log_from_strerror(level, component, cmd) \ 1107 do \ 1108 { \ 1109 GNUNET_log_from (level, \ 1110 component, \ 1111 dgettext ("gnunet", \ 1112 "`%s' failed at %s:%d with error: %s\n"), \ 1113 cmd, \ 1114 __FILE__, \ 1115 __LINE__, \ 1116 strerror (errno)); \ 1117 } while (0) 1118 1119 1120 /** 1121 * @ingroup logging 1122 * Log an error message at log-level 'level' that indicates 1123 * a failure of the command 'cmd' with the message given 1124 * by strerror(errno). 1125 */ 1126 #define GNUNET_log_strerror_file(level, cmd, filename) \ 1127 do \ 1128 { \ 1129 GNUNET_log (level, \ 1130 dgettext ("gnunet", \ 1131 "`%s' failed on file `%s' at %s:%d with error: %s\n"), \ 1132 cmd, \ 1133 filename, \ 1134 __FILE__, \ 1135 __LINE__, \ 1136 strerror (errno)); \ 1137 } while (0) 1138 1139 1140 /** 1141 * @ingroup logging 1142 * Log an error message at log-level 'level' that indicates 1143 * a failure of the command 'cmd' with the message given 1144 * by strerror(errno). 1145 */ 1146 #define GNUNET_log_from_strerror_file(level, component, cmd, filename) \ 1147 do \ 1148 { \ 1149 GNUNET_log_from (level, \ 1150 component, \ 1151 dgettext ("gnunet", \ 1152 "`%s' failed on file `%s' at %s:%d with error: %s\n"), \ 1153 cmd, \ 1154 filename, \ 1155 __FILE__, \ 1156 __LINE__, \ 1157 strerror (errno)); \ 1158 } while (0) 1159 1160 /* ************************* endianness conversion ****************** */ 1161 1162 #ifdef htobe64 1163 1164 #define GNUNET_htonll(n) htobe64 (n) 1165 1166 #else 1167 /** 1168 * Convert unsigned 64-bit integer to network byte order. 1169 * 1170 * @param n 1171 * The value in host byte order. 1172 * 1173 * @return The same value in network byte order. 1174 */ 1175 uint64_t 1176 GNUNET_htonll (uint64_t n); 1177 1178 #endif 1179 1180 1181 #ifdef be64toh 1182 1183 #define GNUNET_ntohll(n) be64toh (n) 1184 1185 #else 1186 /** 1187 * Convert unsigned 64-bit integer to host byte order. 1188 * 1189 * @param n 1190 * The value in network byte order. 1191 * 1192 * @return The same value in host byte order. 1193 */ 1194 uint64_t 1195 GNUNET_ntohll (uint64_t n); 1196 1197 #endif 1198 1199 1200 /** 1201 * Convert double to network byte order. 1202 * 1203 * @param d 1204 * The value in host byte order. 1205 * 1206 * @return The same value in network byte order. 1207 */ 1208 double 1209 GNUNET_hton_double (double d); 1210 1211 1212 /** 1213 * Convert double to host byte order 1214 * 1215 * @param d 1216 * The value in network byte order. 1217 * 1218 * @return The same value in host byte order. 1219 */ 1220 double 1221 GNUNET_ntoh_double (double d); 1222 1223 1224 /* ************************* allocation functions ****************** */ 1225 1226 /** 1227 * @ingroup memory 1228 * Maximum allocation with GNUNET_malloc macro. 1229 */ 1230 #define GNUNET_MAX_MALLOC_CHECKED (1024 * 1024 * 40) 1231 1232 /** 1233 * @ingroup memory 1234 * Allocate a struct or union of the given @a type. 1235 * Wrapper around #GNUNET_malloc that returns a pointer 1236 * to the newly created object of the correct type. 1237 * 1238 * @param type name of the struct or union, i.e. pass 'struct Foo'. 1239 */ 1240 #define GNUNET_new(type) (type *) GNUNET_malloc (sizeof(type)) 1241 1242 1243 /** 1244 * Compare memory in @a a and @a b, where both must be of 1245 * the same pointer type. 1246 * 1247 * Do NOT use this function on arrays, it would only compare 1248 * the first element! 1249 */ 1250 #define GNUNET_memcmp(a, b) \ 1251 ({ \ 1252 const typeof (*b) * _a = (a); \ 1253 const typeof (*a) * _b = (b); \ 1254 memcmp (_a, _b, sizeof(*a)); \ 1255 }) 1256 1257 1258 /** 1259 * Compare memory in @a b1 and @a b2 in constant time, suitable for private 1260 * data. 1261 * 1262 * @param b1 some buffer of size @a len 1263 * @param b2 another buffer of size @a len 1264 * @param len number of bytes in @a b1 and @a b2 1265 * @return 0 if buffers are equal, 1266 */ 1267 int 1268 GNUNET_memcmp_ct_ (const void *b1, 1269 const void *b2, 1270 size_t len); 1271 1272 /** 1273 * Compare memory in @a a and @a b in constant time, suitable for private 1274 * data. Both @a a and @a b must be of the same pointer type. 1275 * 1276 * Do NOT use this function on arrays, it would only compare 1277 * the first element! 1278 */ 1279 #define GNUNET_memcmp_priv(a, b) \ 1280 ({ \ 1281 const typeof (*b) * _a = (a); \ 1282 const typeof (*a) * _b = (b); \ 1283 GNUNET_memcmp_ct_ (_a, _b, sizeof(*a)); \ 1284 }) 1285 1286 1287 /** 1288 * Check that memory in @a a is all zeros. @a a must be a pointer. 1289 * 1290 * @param a pointer to @a n bytes which should be tested for the 1291 * entire memory being zero'ed out. 1292 * @param n number of bytes in @a to be tested 1293 * @return true if @a a is zero, false_NO otherwise 1294 */ 1295 bool 1296 GNUNET_is_zero_ (const void *a, 1297 size_t n); 1298 1299 1300 /** 1301 * Check that memory in @a a is all zeros. @a a must be a pointer. 1302 * 1303 * @param a pointer to a struct which should be tested for the 1304 * entire memory being zero'ed out. 1305 * @return GNUNET_YES if a is zero, GNUNET_NO otherwise 1306 */ 1307 #define GNUNET_is_zero(a) \ 1308 GNUNET_is_zero_ ((a), sizeof (*(a))) 1309 1310 1311 /** 1312 * Call memcpy() but check for @a n being 0 first. In the latter 1313 * case, it is now safe to pass NULL for @a src or @a dst. 1314 * Unlike traditional memcpy(), returns nothing. 1315 * 1316 * @param dst destination of the copy, may be NULL if @a n is zero 1317 * @param src source of the copy, may be NULL if @a n is zero 1318 * @param n number of bytes to copy 1319 */ 1320 #define GNUNET_memcpy(dst, src, n) \ 1321 do \ 1322 { \ 1323 if (0 != n) \ 1324 { \ 1325 (void) memcpy (dst, src, n); \ 1326 } \ 1327 } while (0) 1328 1329 1330 /* *INDENT-OFF* */ 1331 /** 1332 * @ingroup memory 1333 * Allocate a size @a n array with structs or unions of the given @a type. 1334 * Wrapper around #GNUNET_malloc that returns a pointer 1335 * to the newly created objects of the correct type. 1336 * 1337 * @param n number of elements in the array 1338 * @param type name of the struct or union, i.e. pass 'struct Foo'. 1339 */ 1340 #define GNUNET_new_array(n, type) ({ \ 1341 GNUNET_assert (SIZE_MAX / sizeof (type) >= n); \ 1342 (type *) GNUNET_malloc ((n) * sizeof(type)); \ 1343 }) 1344 /* *INDENT-ON* */ 1345 1346 /** 1347 * @ingroup memory 1348 * Wrapper around malloc. Allocates size bytes of memory. 1349 * The memory will be zero'ed out. 1350 * 1351 * @param size the number of bytes to allocate, must be 1352 * smaller than 40 MB. 1353 * @return pointer to size bytes of memory, never NULL (!) 1354 */ 1355 #define GNUNET_malloc(size) GNUNET_xmalloc_ (size, __FILE__, __LINE__) 1356 1357 /** 1358 * @ingroup memory 1359 * Allocate and initialize a block of memory. 1360 * 1361 * @param buf data to initialize the block with 1362 * @param size the number of bytes in buf (and size of the allocation) 1363 * @return pointer to size bytes of memory, never NULL (!) 1364 */ 1365 #define GNUNET_memdup(buf, size) GNUNET_xmemdup_ (buf, size, __FILE__, __LINE__) 1366 1367 /** 1368 * @ingroup memory 1369 * Wrapper around malloc. Allocates size bytes of memory. 1370 * The memory will be zero'ed out. 1371 * 1372 * @param size the number of bytes to allocate 1373 * @return pointer to size bytes of memory, NULL if we do not have enough memory 1374 */ 1375 #define GNUNET_malloc_large(size) \ 1376 GNUNET_xmalloc_unchecked_ (size, __FILE__, __LINE__) 1377 1378 1379 /** 1380 * @ingroup memory 1381 * Wrapper around realloc. Reallocates size bytes of memory. 1382 * The content of the intersection of the new and old size will be unchanged. 1383 * 1384 * @param ptr the pointer to reallocate 1385 * @param size the number of bytes to reallocate 1386 * @return pointer to size bytes of memory 1387 */ 1388 #define GNUNET_realloc(ptr, size) \ 1389 GNUNET_xrealloc_ (ptr, size, __FILE__, __LINE__) 1390 1391 1392 /** 1393 * @ingroup memory 1394 * Wrapper around free. Frees the memory referred to by ptr. 1395 * Note that it is generally better to free memory that was 1396 * allocated with #GNUNET_array_grow using #GNUNET_array_grow(mem, size, 0) instead of #GNUNET_free_nz. 1397 * 1398 * @param ptr location where to free the memory. ptr must have 1399 * been returned by #GNUNET_strdup, #GNUNET_strndup, #GNUNET_malloc or #GNUNET_array_grow earlier. NULL is allowed. 1400 */ 1401 #define GNUNET_free_nz(ptr) GNUNET_xfree_ (ptr, __FILE__, __LINE__) 1402 1403 1404 /** 1405 * @ingroup memory 1406 * Wrapper around free. Frees the memory referred to by ptr and sets ptr to NULL. 1407 * Note that it is generally better to free memory that was 1408 * allocated with #GNUNET_array_grow using #GNUNET_array_grow(mem, size, 0) instead of #GNUNET_free. 1409 * 1410 * @a ptr will be set to NULL. Use #GNUNET_free_nz() if @a ptr is not an L-value. 1411 * 1412 * @param ptr location where to free the memory. ptr must have 1413 * been returned by #GNUNET_strdup, #GNUNET_strndup, #GNUNET_malloc or #GNUNET_array_grow earlier. NULL is allowed. 1414 */ 1415 #define GNUNET_free(ptr) do { \ 1416 GNUNET_xfree_ (ptr, __FILE__, __LINE__); \ 1417 ptr = NULL; \ 1418 } while (0) 1419 1420 1421 /** 1422 * @ingroup memory 1423 * Wrapper around #GNUNET_xstrdup_. Makes a copy of the zero-terminated string 1424 * pointed to by a. 1425 * 1426 * @param a pointer to a zero-terminated string 1427 * @return a copy of the string including zero-termination 1428 */ 1429 #define GNUNET_strdup(a) GNUNET_xstrdup_ (a, __FILE__, __LINE__) 1430 1431 1432 /** 1433 * @ingroup memory 1434 * Wrapper around #GNUNET_xstrndup_. Makes a partial copy of the string 1435 * pointed to by a. 1436 * 1437 * @param a pointer to a string 1438 * @param length of the string to duplicate 1439 * @return a partial copy of the string including zero-termination 1440 */ 1441 #define GNUNET_strndup(a, length) \ 1442 GNUNET_xstrndup_ (a, length, __FILE__, __LINE__) 1443 1444 /** 1445 * @ingroup memory 1446 * Grow a well-typed (!) array. This is a convenience 1447 * method to grow a vector @a arr of size @a size 1448 * to the new (target) size @a tsize. 1449 * <p> 1450 * 1451 * Example (simple, well-typed stack): 1452 * 1453 * <pre> 1454 * static struct foo * myVector = NULL; 1455 * static int myVecLen = 0; 1456 * 1457 * static void push(struct foo * elem) { 1458 * GNUNET_array_grow(myVector, myVecLen, myVecLen+1); 1459 * GNUNET_memcpy(&myVector[myVecLen-1], elem, sizeof(struct foo)); 1460 * } 1461 * 1462 * static void pop(struct foo * elem) { 1463 * if (myVecLen == 0) die(); 1464 * GNUNET_memcpy(elem, myVector[myVecLen-1], sizeof(struct foo)); 1465 * GNUNET_array_grow(myVector, myVecLen, myVecLen-1); 1466 * } 1467 * </pre> 1468 * 1469 * @param arr base-pointer of the vector, may be NULL if size is 0; 1470 * will be updated to reflect the new address. The TYPE of 1471 * arr is important since size is the number of elements and 1472 * not the size in bytes 1473 * @param size the number of elements in the existing vector (number 1474 * of elements to copy over), will be updated with the new 1475 * array size 1476 * @param tsize the target size for the resulting vector, use 0 to 1477 * free the vector (then, arr will be NULL afterwards). 1478 */ 1479 #define GNUNET_array_grow(arr, size, tsize) \ 1480 GNUNET_xgrow_ ((void **) &(arr), \ 1481 sizeof((arr)[0]), \ 1482 &size, \ 1483 tsize, \ 1484 __FILE__, \ 1485 __LINE__) 1486 1487 /** 1488 * @ingroup memory 1489 * Append an element to an array (growing the array by one). 1490 * 1491 * @param arr base-pointer of the vector, may be NULL if @a len is 0; 1492 * will be updated to reflect the new address. The TYPE of 1493 * arr is important since size is the number of elements and 1494 * not the size in bytes 1495 * @param len the number of elements in the existing vector (number 1496 * of elements to copy over), will be updated with the new 1497 * array length 1498 * @param element the element that will be appended to the array 1499 */ 1500 #define GNUNET_array_append(arr, len, element) \ 1501 do \ 1502 { \ 1503 GNUNET_assert ((len) + 1 > (len)); \ 1504 GNUNET_array_grow (arr, len, len + 1); \ 1505 (arr) [len - 1] = element; \ 1506 } while (0) 1507 1508 1509 /** 1510 * @ingroup memory 1511 * Append @a arr2 to @a arr1 (growing @a arr1 1512 * as needed). The @a arr2 array is left unchanged. Naturally 1513 * this function performs a shallow copy. Both arrays must have 1514 * the same type for their elements. 1515 * 1516 * @param arr1 base-pointer of the vector, may be NULL if @a len is 0; 1517 * will be updated to reflect the new address. The TYPE of 1518 * arr is important since size is the number of elements and 1519 * not the size in bytes 1520 * @param len1 the number of elements in the existing vector (number 1521 * of elements to copy over), will be updated with the new 1522 * array size 1523 * @param arr2 base-pointer a second array to concatenate, may be NULL if @a len2 is 0; 1524 * will be updated to reflect the new address. The TYPE of 1525 * arr is important since size is the number of elements and 1526 * not the size in bytes 1527 * @param len2 the number of elements in the existing vector (number 1528 * of elements to copy over), will be updated with the new 1529 * array size 1530 1531 */ 1532 #define GNUNET_array_concatenate(arr1, len1, arr2, len2) \ 1533 do \ 1534 { \ 1535 const typeof (*arr2) * _a1 = (arr1); \ 1536 const typeof (*arr1) * _a2 = (arr2); \ 1537 GNUNET_assert ((len1) + (len2) >= (len1)); \ 1538 GNUNET_assert (SIZE_MAX / sizeof (*_a1) >= ((len1) + (len2))); \ 1539 GNUNET_array_grow (arr1, len1, (len1) + (len2)); \ 1540 memcpy (&(arr1) [(len1) - (len2)], _a2, (len2) * sizeof (*arr1)); \ 1541 } while (0) 1542 1543 1544 /** 1545 * @ingroup memory 1546 * Like snprintf, just aborts if the buffer is of insufficient size. 1547 * 1548 * @param buf pointer to buffer that is written to 1549 * @param size number of bytes in @a buf 1550 * @param format format strings 1551 * @param ... data for format string 1552 * @return number of bytes written to buf or negative value on error 1553 */ 1554 int 1555 GNUNET_snprintf (char *buf, 1556 size_t size, 1557 const char *format, 1558 ...) 1559 __attribute__ ((format (printf, 3, 4))); 1560 1561 1562 /** 1563 * @ingroup memory 1564 * Like asprintf, just portable. 1565 * 1566 * @param buf set to a buffer of sufficient size (allocated, caller must free) 1567 * @param format format string (see printf, fprintf, etc.) 1568 * @param ... data for format string 1569 * @return number of bytes in "*buf" excluding 0-termination 1570 */ 1571 int 1572 GNUNET_asprintf (char **buf, 1573 const char *format, 1574 ...) 1575 __attribute__ ((format (printf, 2, 3))); 1576 1577 1578 /* ************** internal implementations, use macros above! ************** */ 1579 1580 /** 1581 * Allocate memory. Checks the return value, aborts if no more 1582 * memory is available. Don't use GNUNET_xmalloc_ directly. Use the 1583 * #GNUNET_malloc macro. 1584 * The memory will be zero'ed out. 1585 * 1586 * @param size number of bytes to allocate 1587 * @param filename where is this call being made (for debugging) 1588 * @param linenumber line where this call is being made (for debugging) 1589 * @return allocated memory, never NULL 1590 */ 1591 void * 1592 GNUNET_xmalloc_ (size_t size, 1593 const char *filename, 1594 int linenumber); 1595 1596 1597 /** 1598 * Allocate and initialize memory. Checks the return value, aborts if no more 1599 * memory is available. Don't use GNUNET_xmemdup_ directly. Use the 1600 * #GNUNET_memdup macro. 1601 * 1602 * @param buf buffer to initialize from (must contain size bytes) 1603 * @param size number of bytes to allocate 1604 * @param filename where is this call being made (for debugging) 1605 * @param linenumber line where this call is being made (for debugging) 1606 * @return allocated memory, never NULL 1607 */ 1608 void * 1609 GNUNET_xmemdup_ (const void *buf, 1610 size_t size, 1611 const char *filename, 1612 int linenumber); 1613 1614 1615 /** 1616 * Allocate memory. This function does not check if the allocation 1617 * request is within reasonable bounds, allowing allocations larger 1618 * than 40 MB. If you don't expect the possibility of very large 1619 * allocations, use #GNUNET_malloc instead. The memory will be zero'ed 1620 * out. 1621 * 1622 * @param size number of bytes to allocate 1623 * @param filename where is this call being made (for debugging) 1624 * @param linenumber line where this call is being made (for debugging) 1625 * @return pointer to size bytes of memory, NULL if we do not have enough memory 1626 */ 1627 void * 1628 GNUNET_xmalloc_unchecked_ (size_t size, 1629 const char *filename, 1630 int linenumber); 1631 1632 1633 /** 1634 * Reallocate memory. Checks the return value, aborts if no more 1635 * memory is available. 1636 */ 1637 void * 1638 GNUNET_xrealloc_ (void *ptr, 1639 size_t n, 1640 const char *filename, 1641 int linenumber); 1642 1643 1644 /** 1645 * Free memory. Merely a wrapper for the case that we 1646 * want to keep track of allocations. Don't use GNUNET_xfree_ 1647 * directly. Use the #GNUNET_free macro. 1648 * 1649 * @param ptr pointer to memory to free 1650 * @param filename where is this call being made (for debugging) 1651 * @param linenumber line where this call is being made (for debugging) 1652 */ 1653 void 1654 GNUNET_xfree_ (void *ptr, 1655 const char *filename, 1656 int linenumber); 1657 1658 1659 /** 1660 * Dup a string. Don't call GNUNET_xstrdup_ directly. Use the #GNUNET_strdup macro. 1661 * @param str string to duplicate 1662 * @param filename where is this call being made (for debugging) 1663 * @param linenumber line where this call is being made (for debugging) 1664 * @return the duplicated string 1665 */ 1666 char * 1667 GNUNET_xstrdup_ (const char *str, 1668 const char *filename, 1669 int linenumber); 1670 1671 /** 1672 * Dup partially a string. Don't call GNUNET_xstrndup_ directly. Use the #GNUNET_strndup macro. 1673 * 1674 * @param str string to duplicate 1675 * @param len length of the string to duplicate 1676 * @param filename where is this call being made (for debugging) 1677 * @param linenumber line where this call is being made (for debugging) 1678 * @return the duplicated string 1679 */ 1680 char * 1681 GNUNET_xstrndup_ (const char *str, 1682 size_t len, 1683 const char *filename, 1684 int linenumber); 1685 1686 /** 1687 * Grow an array, the new elements are zeroed out. 1688 * Grows old by (*oldCount-newCount)*elementSize 1689 * bytes and sets *oldCount to newCount. 1690 * 1691 * Don't call GNUNET_xgrow_ directly. Use the #GNUNET_array_grow macro. 1692 * 1693 * @param old address of the pointer to the array 1694 * *old may be NULL 1695 * @param elementSize the size of the elements of the array 1696 * @param oldCount address of the number of elements in the *old array 1697 * @param newCount number of elements in the new array, may be 0 (then *old will be NULL afterwards) 1698 * @param filename where is this call being made (for debugging) 1699 * @param linenumber line where this call is being made (for debugging) 1700 */ 1701 void 1702 GNUNET_xgrow_ (void **old, 1703 size_t elementSize, 1704 unsigned int *oldCount, 1705 unsigned int newCount, 1706 const char *filename, 1707 int linenumber); 1708 1709 1710 /** 1711 * @ingroup memory 1712 * Create a copy of the given message. 1713 * 1714 * @param msg message to copy 1715 * @return duplicate of the message 1716 */ 1717 struct GNUNET_MessageHeader * 1718 GNUNET_copy_message (const struct GNUNET_MessageHeader *msg); 1719 1720 1721 /** 1722 * Set the async scope for the current thread. 1723 * 1724 * @param aid the async scope identifier 1725 * @param[out] old_scope location to save the old scope 1726 */ 1727 void 1728 GNUNET_async_scope_enter (const struct GNUNET_AsyncScopeId *aid, 1729 struct GNUNET_AsyncScopeSave *old_scope); 1730 1731 1732 /** 1733 * Clear the current thread's async scope. 1734 * 1735 * @param old_scope scope to restore 1736 */ 1737 void 1738 GNUNET_async_scope_restore (struct GNUNET_AsyncScopeSave *old_scope); 1739 1740 1741 /** 1742 * Get the current async scope. 1743 * 1744 * @param[out] scope_ret pointer to where the result is stored 1745 */ 1746 void 1747 GNUNET_async_scope_get (struct GNUNET_AsyncScopeSave *scope_ret); 1748 1749 1750 /** 1751 * Generate a fresh async scope identifier. 1752 * 1753 * @param[out] aid_ret pointer to where the result is stored 1754 */ 1755 void 1756 GNUNET_async_scope_fresh (struct GNUNET_AsyncScopeId *aid_ret); 1757 1758 1759 #if __STDC_VERSION__ < 199901L 1760 #if __GNUC__ >= 2 1761 #define __func__ __FUNCTION__ 1762 #else 1763 #define __func__ "<unknown>" 1764 #endif 1765 #endif 1766 1767 1768 /** 1769 * Valid task priorities. Use these, do not pass random integers! 1770 * For various reasons (#3862 -- building with QT Creator, and 1771 * our restricted cross-compilation with emscripten) this cannot 1772 * be in gnunet_scheduler_lib.h, but it works if we declare it here. 1773 * Naturally, logically this is part of the scheduler. 1774 */ 1775 enum GNUNET_SCHEDULER_Priority 1776 { 1777 /** 1778 * Run with the same priority as the current job. 1779 */ 1780 GNUNET_SCHEDULER_PRIORITY_KEEP = 0, 1781 1782 /** 1783 * Run when otherwise idle. 1784 */ 1785 GNUNET_SCHEDULER_PRIORITY_IDLE = 1, 1786 1787 /** 1788 * Run as background job (higher than idle, 1789 * lower than default). 1790 */ 1791 GNUNET_SCHEDULER_PRIORITY_BACKGROUND = 2, 1792 1793 /** 1794 * Run with the default priority (normal 1795 * P2P operations). Any task that is scheduled 1796 * without an explicit priority being specified 1797 * will run with this priority. 1798 */ 1799 GNUNET_SCHEDULER_PRIORITY_DEFAULT = 3, 1800 1801 /** 1802 * Run with high priority (important requests). 1803 * Higher than DEFAULT. 1804 */ 1805 GNUNET_SCHEDULER_PRIORITY_HIGH = 4, 1806 1807 /** 1808 * Run with priority for interactive tasks. 1809 * Higher than "HIGH". 1810 */ 1811 GNUNET_SCHEDULER_PRIORITY_UI = 5, 1812 1813 /** 1814 * Run with priority for urgent tasks. Use 1815 * for things like aborts and shutdowns that 1816 * need to preempt "UI"-level tasks. 1817 * Higher than "UI". 1818 */ 1819 GNUNET_SCHEDULER_PRIORITY_URGENT = 6, 1820 1821 /** 1822 * This is an internal priority level that is only used for tasks 1823 * that are being triggered due to shutdown (they have automatically 1824 * highest priority). User code must not use this priority level 1825 * directly. Tasks run with this priority level that internally 1826 * schedule other tasks will see their original priority level 1827 * be inherited (unless otherwise specified). 1828 */ 1829 GNUNET_SCHEDULER_PRIORITY_SHUTDOWN = 7, 1830 1831 /** 1832 * Number of priorities (must be the last priority). 1833 * This priority must not be used by clients. 1834 */ 1835 GNUNET_SCHEDULER_PRIORITY_COUNT = 8 1836 }; 1837 1838 1839 /* *INDENT-OFF* */ 1840 1841 #if 0 /* keep Emacsens' auto-indent happy */ 1842 { 1843 #endif 1844 #ifdef __cplusplus 1845 } 1846 #endif 1847 1848 #endif /* GNUNET_COMMON_H */