src/include/gnunet_common.h

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