src/include/gnunet_common.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2006, 2009 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 2, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  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  */
  30 #ifndef GNUNET_COMMON_H
  31 #define GNUNET_COMMON_H
  32
  33 /**
  34  * Version of the API (for entire gnunetutil.so library).
  35  */
  36 #define GNUNET_UTIL_VERSION 0x00000000
  37
  38 /**
  39  * Name used for "services" that are actually command-line
  40  * programs invoked by the end user.
  41  */
  42 #define GNUNET_CLIENT_SERVICE_NAME "client"
  43
  44 /**
  45  * Named constants for return values.  The following
  46  * invariants hold: "GNUNET_NO == 0" (to allow "if (GNUNET_NO)")
  47  * "GNUNET_OK != GNUNET_SYSERR", "GNUNET_OK != GNUNET_NO", "GNUNET_NO != GNUNET_SYSERR"
  48  * and finally "GNUNET_YES != GNUNET_NO".
  49  */
  50 #define GNUNET_OK      1
  51 #define GNUNET_SYSERR -1
  52 #define GNUNET_YES     1
  53 #define GNUNET_NO      0
  54
  55 #define GNUNET_MIN(a,b) (((a) < (b)) ? (a) : (b))
  56
  57 #define GNUNET_MAX(a,b) (((a) > (b)) ? (a) : (b))
  58
  59 /**
  60  * gcc-ism to get packed structs.
  61  */
  62 #define GNUNET_PACKED __attribute__((packed))
  63
  64
  65 /* ************************ super-general types *********************** */
  66
  67 /**
  68  * Header for all communications.
  69  */
  70 struct GNUNET_MessageHeader
  71 {
  72
  73   /**
  74    * The length of the struct (in bytes, including the length field itself),
  75    * in big-endian format.
  76    */
  77   uint16_t size GNUNET_PACKED;
  78
  79   /**
  80    * The type of the message (GNUNET_MESSAGE_TYPE_XXXX), in big-endian format.
  81    */
  82   uint16_t type GNUNET_PACKED;
  83
  84 };
  85
  86
  87 /**
  88  * @brief 512-bit hashcode
  89  */
  90 typedef struct
  91 {
  92   uint32_t bits[512 / 8 / sizeof (uint32_t)];   /* = 16 */
  93 }
  94 GNUNET_HashCode;
  95
  96
  97 /**
  98  * The identity of the host (basically the SHA-512 hashcode of
  99  * it's public key).
 100  */
 101 struct GNUNET_PeerIdentity
 102 {
 103   GNUNET_HashCode hashPubKey GNUNET_PACKED;
 104 };
 105
 106
 107 /**
 108  * Function called with a filename.
 109  *
 110  * @param cls closure
 111  * @param filename complete filename (absolute path)
 112  * @return GNUNET_OK to continue to iterate,
 113  *  GNUNET_SYSERR to abort iteration with error!
 114  */
 115 typedef int (*GNUNET_FileNameCallback) (void *cls, const char *filename);
 116
 117
 118 /* ****************************** logging ***************************** */
 119
 120 /**
 121  * Types of errors.
 122  */
 123 enum GNUNET_ErrorType
 124 {
 125   GNUNET_ERROR_TYPE_ERROR = 1,
 126   GNUNET_ERROR_TYPE_WARNING = 2,
 127   GNUNET_ERROR_TYPE_INFO = 4,
 128   GNUNET_ERROR_TYPE_DEBUG = 8,
 129   GNUNET_ERROR_TYPE_INVALID = 16,
 130   GNUNET_ERROR_TYPE_BULK = 32
 131 };
 132
 133 /**
 134  * User-defined handler for log messages.
 135  *
 136  * @param cls closure
 137  * @param kind severeity
 138  * @param component what component is issuing the message?
 139  * @param date when was the message logged?
 140  * @param message what is the message
 141  */
 142 typedef void (*GNUNET_Logger) (void *cls,
 143                                enum GNUNET_ErrorType kind,
 144                                const char *component,
 145                                const char *date, const char *message);
 146
 147 /**
 148  * Main log function.
 149  *
 150  * @param kind how serious is the error?
 151  * @param message what is the message (format string)
 152  * @param ... arguments for format string
 153  */
 154 void GNUNET_log (enum GNUNET_ErrorType kind, const char *message, ...);
 155
 156
 157
 158 /**
 159  * Log function that specifies an alternative component.
 160  * This function should be used by plugins.
 161  *
 162  * @param kind how serious is the error?
 163  * @param comp component responsible for generating the message
 164  * @param message what is the message (format string)
 165  * @param ... arguments for format string
 166  */
 167 void
 168 GNUNET_log_from (enum GNUNET_ErrorType kind,
 169                  const char *comp, const char *message, ...);
 170
 171
 172 /**
 173  * Ignore the next n calls to the log function.
 174  *
 175  * @param n number of log calls to ignore
 176  * @param check_reset GNUNET_YES to assert that the log skip counter is currently zero
 177  */
 178 void
 179 GNUNET_log_skip (unsigned int n, int check_reset);
 180
 181
 182 /**
 183  * Setup logging.
 184  *
 185  * @param comp default component to use
 186  * @param loglevel what types of messages should be logged
 187  * @param logfile change logging to logfile (use NULL to keep stderr)
 188  * @return GNUNET_OK on success, GNUNET_SYSERR if logfile could not be opened
 189  */
 190 int
 191 GNUNET_log_setup (const char *comp,
 192                   const char *loglevel, const char *logfile);
 193
 194 /**
 195  * Add a custom logger.
 196  *
 197  * @param logger log function
 198  * @param logger_cls closure for logger
 199  */
 200 void GNUNET_logger_add (GNUNET_Logger logger, void *logger_cls);
 201
 202 /**
 203  * Remove a custom logger.
 204  *
 205  * @param logger log function
 206  * @param logger_cls closure for logger
 207  */
 208 void GNUNET_logger_remove (GNUNET_Logger logger, void *logger_cls);
 209
 210
 211 /**
 212  * Convert a hash value to a string (for printing debug messages).
 213  * This is one of the very few calls in the entire API that is
 214  * NOT reentrant!
 215  *
 216  * @param hc the hash code
 217  * @return string
 218  */
 219 const char *GNUNET_h2s (const GNUNET_HashCode *hc);
 220
 221
 222 /**
 223  * Convert a peer identity to a string (for printing debug messages).
 224  * This is one of the very few calls in the entire API that is
 225  * NOT reentrant!
 226  *
 227  * @param pid the peer identity
 228  * @return string form of the pid; will be overwritten by next
 229  *         call to GNUNET_i2s.
 230  */
 231 const char *GNUNET_i2s (const struct GNUNET_PeerIdentity *pid);
 232
 233
 234 /**
 235  * Convert a "struct sockaddr*" (IPv4 or IPv6 address) to a string
 236  * (for printing debug messages).  This is one of the very few calls
 237  * in the entire API that is NOT reentrant!
 238  *
 239  * @param addr the address
 240  * @param addrlen the length of the address
 241  * @return nicely formatted string for the address
 242  *  will be overwritten by next call to GNUNET_a2s.
 243  */
 244 const char *GNUNET_a2s (const struct sockaddr *addr,
 245                         socklen_t addrlen);
 246
 247 /**
 248  * Convert error type to string.
 249  *
 250  * @param kind type to convert
 251  * @return string corresponding to the type
 252  */
 253 const char *GNUNET_error_type_to_string (enum GNUNET_ErrorType kind);
 254
 255 /**
 256  * Use this for fatal errors that cannot be handled
 257  */
 258 #define GNUNET_assert(cond) do { if (! (cond)) { GNUNET_log(GNUNET_ERROR_TYPE_ERROR, _("Assertion failed at %s:%d.\n"), __FILE__, __LINE__); abort(); } } while(0)
 259
 260 /**
 261  * Use this for fatal errors that cannot be handled
 262  */
 263 #define GNUNET_assert_at(cond, f, l) do { if (! (cond)) { GNUNET_log(GNUNET_ERROR_TYPE_ERROR, _("Assertion failed at %s:%d.\n"), f, l); abort(); } } while(0)
 264
 265 /**
 266  * Use this for internal assertion violations that are
 267  * not fatal (can be handled) but should not occur.
 268  */
 269 #define GNUNET_break(cond)  do { if (! (cond)) { GNUNET_log(GNUNET_ERROR_TYPE_ERROR, _("Assertion failed at %s:%d.\n"), __FILE__, __LINE__); } } while(0)
 270
 271 /**
 272  * Use this for assertion violations caused by other
 273  * peers (i.e. protocol violations).  We do not want to
 274  * confuse end-users (say, some other peer runs an
 275  * older, broken or incompatible GNUnet version), but
 276  * we still want to see these problems during
 277  * development and testing.  "OP == other peer".
 278  */
 279 #define GNUNET_break_op(cond)  do { if (! (cond)) { GNUNET_log(GNUNET_ERROR_TYPE_WARNING, _("External protocol violation detected at %s:%d.\n"), __FILE__, __LINE__); } } while(0)
 280
 281 /**
 282  * Log an error message at log-level 'level' that indicates
 283  * a failure of the command 'cmd' with the message given
 284  * by strerror(errno).
 285  */
 286 #define GNUNET_log_strerror(level, cmd) do { GNUNET_log(level, _("`%s' failed at %s:%d with error: %s\n"), cmd, __FILE__, __LINE__, STRERROR(errno)); } while(0)
 287
 288 /**
 289  * Log an error message at log-level 'level' that indicates
 290  * a failure of the command 'cmd' with the message given
 291  * by strerror(errno).
 292  */
 293 #define GNUNET_log_strerror_file(level, cmd, filename) do { GNUNET_log(level, _("`%s' failed on file `%s' at %s:%d with error: %s\n"), cmd, filename,__FILE__, __LINE__, STRERROR(errno)); } while(0)
 294
 295 /* ************************* endianess conversion ****************** */
 296
 297 /**
 298  * Convert a long-long to host-byte-order.
 299  * @param n the value in network byte order
 300  * @return the same value in host byte order
 301  */
 302 unsigned long long GNUNET_ntohll (unsigned long long n);
 303
 304 /**
 305  * Convert a long long to network-byte-order.
 306  * @param n the value in host byte order
 307  * @return the same value in network byte order
 308  */
 309 unsigned long long GNUNET_htonll (unsigned long long n);
 310
 311
 312 /* ************************* allocation functions ****************** */
 313
 314 /**
 315  * Maximum allocation with GNUNET_malloc macro.
 316  */
 317 #define GNUNET_MAX_MALLOC_CHECKED (1024 * 1024 * 40)
 318
 319 /**
 320  * Wrapper around malloc. Allocates size bytes of memory.
 321  * The memory will be zero'ed out.
 322  *
 323  * @param size the number of bytes to allocate, must be
 324  *        smaller than 40 MB.
 325  * @return pointer to size bytes of memory
 326  */
 327 #define GNUNET_malloc(size) GNUNET_xmalloc_(size, __FILE__, __LINE__)
 328
 329 /**
 330  * Wrapper around malloc. Allocates size bytes of memory.
 331  * The memory will be zero'ed out.
 332  *
 333  * @param size the number of bytes to allocate
 334  * @return pointer to size bytes of memory
 335  */
 336 #define GNUNET_malloc_large(size) GNUNET_xmalloc_unchecked_(size, __FILE__, __LINE__)
 337
 338 /**
 339  * Wrapper around realloc. Rellocates size bytes of memory.
 340  *
 341  * @param ptr the pointer to reallocate
 342  * @param size the number of bytes to reallocate
 343  * @return pointer to size bytes of memory
 344  */
 345 #define GNUNET_realloc(ptr, size) GNUNET_xrealloc_(ptr, size, __FILE__, __LINE__)
 346
 347 /**
 348  * Wrapper around free. Frees the memory referred to by ptr.
 349  * Note that is is generally better to free memory that was
 350  * allocated with GNUNET_array_grow using GNUNET_array_grow(mem, size, 0) instead of GNUNET_free.
 351  *
 352  * @param ptr location where to free the memory. ptr must have
 353  *     been returned by GNUNET_strdup, GNUNET_malloc or GNUNET_array_grow earlier.
 354  */
 355 #define GNUNET_free(ptr) GNUNET_xfree_(ptr, __FILE__, __LINE__)
 356
 357 /**
 358  * Free the memory pointed to by ptr if ptr is not NULL.
 359  * Equivalent to if (ptr!=null)GNUNET_free(ptr).
 360  *
 361  * @param ptr the location in memory to free
 362  */
 363 #define GNUNET_free_non_null(ptr) do { void * __x__ = ptr; if (__x__ != NULL) { GNUNET_free(__x__); } } while(0)
 364
 365 /**
 366  * Wrapper around GNUNET_strdup.  Makes a copy of the zero-terminated string
 367  * pointed to by a.
 368  *
 369  * @param a pointer to a zero-terminated string
 370  * @return a copy of the string including zero-termination
 371  */
 372 #define GNUNET_strdup(a) GNUNET_xstrdup_(a,__FILE__,__LINE__)
 373
 374 /**
 375  * Grow a well-typed (!) array.  This is a convenience
 376  * method to grow a vector <tt>arr</tt> of size <tt>size</tt>
 377  * to the new (target) size <tt>tsize</tt>.
 378  * <p>
 379  *
 380  * Example (simple, well-typed stack):
 381  *
 382  * <pre>
 383  * static struct foo * myVector = NULL;
 384  * static int myVecLen = 0;
 385  *
 386  * static void push(struct foo * elem) {
 387  *   GNUNET_array_grow(myVector, myVecLen, myVecLen+1);
 388  *   memcpy(&myVector[myVecLen-1], elem, sizeof(struct foo));
 389  * }
 390  *
 391  * static void pop(struct foo * elem) {
 392  *   if (myVecLen == 0) die();
 393  *   memcpy(elem, myVector[myVecLen-1], sizeof(struct foo));
 394  *   GNUNET_array_grow(myVector, myVecLen, myVecLen-1);
 395  * }
 396  * </pre>
 397  *
 398  * @param arr base-pointer of the vector, may be NULL if size is 0;
 399  *        will be updated to reflect the new address. The TYPE of
 400  *        arr is important since size is the number of elements and
 401  *        not the size in bytes
 402  * @param size the number of elements in the existing vector (number
 403  *        of elements to copy over)
 404  * @param tsize the target size for the resulting vector, use 0 to
 405  *        free the vector (then, arr will be NULL afterwards).
 406  */
 407 #define GNUNET_array_grow(arr,size,tsize) GNUNET_xgrow_((void**)&arr, sizeof(arr[0]), &size, tsize, __FILE__, __LINE__)
 408
 409 /**
 410  * Append an element to a list (growing the
 411  * list by one).
 412  */
 413 #define GNUNET_array_append(arr,size,element) do { GNUNET_array_grow(arr,size,size+1); arr[size-1] = element; } while(0)
 414
 415 /**
 416  * Like snprintf, just aborts if the buffer is of insufficient size.
 417  *
 418  * @param buf pointer to buffer that is written to
 419  * @param size number of bytes in buf
 420  * @param format format strings
 421  * @param ... data for format string
 422  * @return number of bytes written to buf or negative value on error
 423  */
 424 int GNUNET_snprintf (char *buf, size_t size, const char *format, ...);
 425
 426
 427 /**
 428  * Like asprintf, just portable.
 429  *
 430  * @param buf set to a buffer of sufficient size (allocated, caller must free)
 431  * @param format format string (see printf, fprintf, etc.)
 432  * @param ... data for format string
 433  * @return number of bytes in "*buf" excluding 0-termination
 434  */
 435 int GNUNET_asprintf (char **buf, const char *format, ...);
 436
 437
 438 /* ************** internal implementations, use macros above! ************** */
 439
 440 /**
 441  * Allocate memory. Checks the return value, aborts if no more
 442  * memory is available.  Don't use GNUNET_xmalloc_ directly. Use the
 443  * GNUNET_malloc macro.
 444  * The memory will be zero'ed out.
 445  *
 446  * @param size number of bytes to allocate
 447  * @param filename where is this call being made (for debugging)
 448  * @param linenumber line where this call is being made (for debugging)
 449  * @return allocated memory, never NULL
 450  */
 451 void *GNUNET_xmalloc_ (size_t size, const char *filename, int linenumber);
 452
 453
 454 /**
 455  * Allocate memory.  This function does not check if the
 456  * allocation request is within reasonable bounds, allowing
 457  * allocations larger than 40 MB.  If you don't expect the
 458  * possibility of very large allocations, use GNUNET_malloc instead.
 459  * The memory will be zero'ed out.
 460  *
 461  * @param size number of bytes to allocate
 462  * @param filename where is this call being made (for debugging)
 463  * @param linenumber line where this call is being made (for debugging)
 464  * @return allocated memory, never NULL
 465  */
 466 void *GNUNET_xmalloc_unchecked_ (size_t size,
 467                                  const char *filename, int linenumber);
 468
 469 /**
 470  * Reallocate memory. Checks the return value, aborts if no more
 471  * memory is available.
 472  */
 473 void *GNUNET_xrealloc_ (void *ptr,
 474                         const size_t n, const char *filename, int linenumber);
 475
 476 /**
 477  * Free memory. Merely a wrapper for the case that we
 478  * want to keep track of allocations.  Don't use GNUNET_xfree_
 479  * directly. Use the GNUNET_free macro.
 480  *
 481  * @param ptr pointer to memory to free
 482  * @param filename where is this call being made (for debugging)
 483  * @param linenumber line where this call is being made (for debugging)
 484  */
 485 void GNUNET_xfree_ (void *ptr, const char *filename, int linenumber);
 486
 487
 488 /**
 489  * Dup a string. Don't call GNUNET_xstrdup_ directly. Use the GNUNET_strdup macro.
 490  * @param str string to duplicate
 491  * @param filename where is this call being made (for debugging)
 492  * @param linenumber line where this call is being made (for debugging)
 493  * @return the duplicated string
 494  */
 495 char *GNUNET_xstrdup_ (const char *str, const char *filename, int linenumber);
 496
 497 /**
 498  * Grow an array, the new elements are zeroed out.
 499  * Grows old by (*oldCount-newCount)*elementSize
 500  * bytes and sets *oldCount to newCount.
 501  *
 502  * Don't call GNUNET_xgrow_ directly. Use the GNUNET_array_grow macro.
 503  *
 504  * @param old address of the pointer to the array
 505  *        *old may be NULL
 506  * @param elementSize the size of the elements of the array
 507  * @param oldCount address of the number of elements in the *old array
 508  * @param newCount number of elements in the new array, may be 0 (then *old will be NULL afterwards)
 509  * @param filename where is this call being made (for debugging)
 510  * @param linenumber line where this call is being made (for debugging)
 511  */
 512 void GNUNET_xgrow_ (void **old,
 513                     size_t elementSize,
 514                     unsigned int *oldCount,
 515                     unsigned int newCount,
 516                     const char *filename, int linenumber);
 517
 518
 519
 520
 521 #if __STDC_VERSION__ < 199901L
 522 # if __GNUC__ >= 2
 523 #  define __func__ __FUNCTION__
 524 # else
 525 #  define __func__ "<unknown>"
 526 # endif
 527 #endif
 528
 529 #endif /*GNUNET_COMMON_H_ */