Clean up doxygen warnings
[asterisk/asterisk.git] / include / asterisk / utils.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2006, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Utility functions
21  */
22
23 #ifndef _ASTERISK_UTILS_H
24 #define _ASTERISK_UTILS_H
25
26 #include "asterisk/network.h"
27
28 #include <time.h>       /* we want to override localtime_r */
29 #include <unistd.h>
30 #include <string.h>
31
32 #include "asterisk/lock.h"
33 #include "asterisk/time.h"
34 #include "asterisk/logger.h"
35 #include "asterisk/localtime.h"
36 #include "asterisk/stringfields.h"
37
38 /*!
39 \note \verbatim
40    Note:
41    It is very important to use only unsigned variables to hold
42    bit flags, as otherwise you can fall prey to the compiler's
43    sign-extension antics if you try to use the top two bits in
44    your variable.
45
46    The flag macros below use a set of compiler tricks to verify
47    that the caller is using an "unsigned int" variable to hold
48    the flags, and nothing else. If the caller uses any other
49    type of variable, a warning message similar to this:
50
51    warning: comparison of distinct pointer types lacks cast
52    will be generated.
53
54    The "dummy" variable below is used to make these comparisons.
55
56    Also note that at -O2 or above, this type-safety checking
57    does _not_ produce any additional object code at all.
58  \endverbatim
59 */
60
61 extern unsigned int __unsigned_int_flags_dummy;
62
63 #define ast_test_flag(p,flag)           ({ \
64                                         typeof ((p)->flags) __p = (p)->flags; \
65                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
66                                         (void) (&__p == &__x); \
67                                         ((p)->flags & (flag)); \
68                                         })
69
70 #define ast_set_flag(p,flag)            do { \
71                                         typeof ((p)->flags) __p = (p)->flags; \
72                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
73                                         (void) (&__p == &__x); \
74                                         ((p)->flags |= (flag)); \
75                                         } while(0)
76
77 #define ast_clear_flag(p,flag)          do { \
78                                         typeof ((p)->flags) __p = (p)->flags; \
79                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
80                                         (void) (&__p == &__x); \
81                                         ((p)->flags &= ~(flag)); \
82                                         } while(0)
83
84 #define ast_copy_flags(dest,src,flagz)  do { \
85                                         typeof ((dest)->flags) __d = (dest)->flags; \
86                                         typeof ((src)->flags) __s = (src)->flags; \
87                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
88                                         (void) (&__d == &__x); \
89                                         (void) (&__s == &__x); \
90                                         (dest)->flags &= ~(flagz); \
91                                         (dest)->flags |= ((src)->flags & (flagz)); \
92                                         } while (0)
93
94 #define ast_set2_flag(p,value,flag)     do { \
95                                         typeof ((p)->flags) __p = (p)->flags; \
96                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
97                                         (void) (&__p == &__x); \
98                                         if (value) \
99                                                 (p)->flags |= (flag); \
100                                         else \
101                                                 (p)->flags &= ~(flag); \
102                                         } while (0)
103
104 #define ast_set_flags_to(p,flag,value)  do { \
105                                         typeof ((p)->flags) __p = (p)->flags; \
106                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
107                                         (void) (&__p == &__x); \
108                                         (p)->flags &= ~(flag); \
109                                         (p)->flags |= (value); \
110                                         } while (0)
111
112
113 /* The following 64-bit flag code can most likely be erased after app_dial
114    is reorganized to either reduce the large number of options, or handle
115    them in some other way. At the time of this writing, app_dial would be
116    the only user of 64-bit option flags */
117
118 extern uint64_t __unsigned_int_flags_dummy64;
119
120 #define ast_test_flag64(p,flag)                 ({ \
121                                         typeof ((p)->flags) __p = (p)->flags; \
122                                         typeof (__unsigned_int_flags_dummy64) __x = 0; \
123                                         (void) (&__p == &__x); \
124                                         ((p)->flags & (flag)); \
125                                         })
126
127 #define ast_set_flag64(p,flag)          do { \
128                                         typeof ((p)->flags) __p = (p)->flags; \
129                                         typeof (__unsigned_int_flags_dummy64) __x = 0; \
130                                         (void) (&__p == &__x); \
131                                         ((p)->flags |= (flag)); \
132                                         } while(0)
133
134 #define ast_clear_flag64(p,flag)                do { \
135                                         typeof ((p)->flags) __p = (p)->flags; \
136                                         typeof (__unsigned_int_flags_dummy64) __x = 0; \
137                                         (void) (&__p == &__x); \
138                                         ((p)->flags &= ~(flag)); \
139                                         } while(0)
140
141 #define ast_copy_flags64(dest,src,flagz)        do { \
142                                         typeof ((dest)->flags) __d = (dest)->flags; \
143                                         typeof ((src)->flags) __s = (src)->flags; \
144                                         typeof (__unsigned_int_flags_dummy64) __x = 0; \
145                                         (void) (&__d == &__x); \
146                                         (void) (&__s == &__x); \
147                                         (dest)->flags &= ~(flagz); \
148                                         (dest)->flags |= ((src)->flags & (flagz)); \
149                                         } while (0)
150
151 #define ast_set2_flag64(p,value,flag)   do { \
152                                         typeof ((p)->flags) __p = (p)->flags; \
153                                         typeof (__unsigned_int_flags_dummy64) __x = 0; \
154                                         (void) (&__p == &__x); \
155                                         if (value) \
156                                                 (p)->flags |= (flag); \
157                                         else \
158                                                 (p)->flags &= ~(flag); \
159                                         } while (0)
160
161 #define ast_set_flags_to64(p,flag,value)        do { \
162                                         typeof ((p)->flags) __p = (p)->flags; \
163                                         typeof (__unsigned_int_flags_dummy64) __x = 0; \
164                                         (void) (&__p == &__x); \
165                                         (p)->flags &= ~(flag); \
166                                         (p)->flags |= (value); \
167                                         } while (0)
168
169
170 /* Non-type checking variations for non-unsigned int flags.  You
171    should only use non-unsigned int flags where required by
172    protocol etc and if you know what you're doing :)  */
173 #define ast_test_flag_nonstd(p,flag) \
174                                         ((p)->flags & (flag))
175
176 #define ast_set_flag_nonstd(p,flag)             do { \
177                                         ((p)->flags |= (flag)); \
178                                         } while(0)
179
180 #define ast_clear_flag_nonstd(p,flag)           do { \
181                                         ((p)->flags &= ~(flag)); \
182                                         } while(0)
183
184 #define ast_copy_flags_nonstd(dest,src,flagz)   do { \
185                                         (dest)->flags &= ~(flagz); \
186                                         (dest)->flags |= ((src)->flags & (flagz)); \
187                                         } while (0)
188
189 #define ast_set2_flag_nonstd(p,value,flag)      do { \
190                                         if (value) \
191                                                 (p)->flags |= (flag); \
192                                         else \
193                                                 (p)->flags &= ~(flag); \
194                                         } while (0)
195
196 #define AST_FLAGS_ALL UINT_MAX
197
198 /*! \brief Structure used to handle boolean flags */
199 struct ast_flags {
200         unsigned int flags;
201 };
202
203 /*! \brief Structure used to handle a large number of boolean flags == used only in app_dial? */
204 struct ast_flags64 {
205         uint64_t flags;
206 };
207
208 struct ast_hostent {
209         struct hostent hp;
210         char buf[1024];
211 };
212
213 /*! \brief Thread-safe gethostbyname function to use in Asterisk */
214 struct hostent *ast_gethostbyname(const char *host, struct ast_hostent *hp);
215
216 /*! \brief Produces MD5 hash based on input string */
217 void ast_md5_hash(char *output, const char *input);
218 /*! \brief Produces SHA1 hash based on input string */
219 void ast_sha1_hash(char *output, const char *input);
220 /*! \brief Produces SHA1 hash based on input string, stored in uint8_t array */
221 void ast_sha1_hash_uint(uint8_t *digest, const char *input);
222
223 int ast_base64encode_full(char *dst, const unsigned char *src, int srclen, int max, int linebreaks);
224
225 #undef MIN
226 #define MIN(a, b) ({ typeof(a) __a = (a); typeof(b) __b = (b); ((__a > __b) ? __b : __a);})
227 #undef MAX
228 #define MAX(a, b) ({ typeof(a) __a = (a); typeof(b) __b = (b); ((__a < __b) ? __b : __a);})
229
230 #define SWAP(a,b) do { typeof(a) __tmp = (a); (a) = (b); (b) = __tmp; } while (0)
231
232 /*!
233  * \brief Encode data in base64
234  * \param dst the destination buffer
235  * \param src the source data to be encoded
236  * \param srclen the number of bytes present in the source buffer
237  * \param max the maximum number of bytes to write into the destination
238  *        buffer, *including* the terminating NULL character.
239  */
240 int ast_base64encode(char *dst, const unsigned char *src, int srclen, int max);
241
242 /*!
243  * \brief Decode data from base64
244  * \param dst the destination buffer
245  * \param src the source buffer
246  * \param max The maximum number of bytes to write into the destination
247  *            buffer.  Note that this function will not ensure that the
248  *            destination buffer is NULL terminated.  So, in general,
249  *            this parameter should be sizeof(dst) - 1.
250  */
251 int ast_base64decode(unsigned char *dst, const char *src, int max);
252
253 #define AST_URI_ALPHANUM     (1 << 0)
254 #define AST_URI_MARK         (1 << 1)
255 #define AST_URI_UNRESERVED   (AST_URI_ALPHANUM | AST_URI_MARK)
256 #define AST_URI_LEGACY_SPACE (1 << 2)
257
258 #define AST_URI_SIP_USER_UNRESERVED (1 << 20)
259
260 extern const struct ast_flags ast_uri_http;
261 extern const struct ast_flags ast_uri_http_legacy;
262 extern const struct ast_flags ast_uri_sip_user;
263
264 /*!
265  * \brief Turn text string to URI-encoded %XX version
266  *
267  * This function encodes characters according to the rules presented in RFC
268  * 2396 and/or RFC 3261 section 19.1.2 and section 25.1.
269  *
270  * Outbuf needs to have more memory allocated than the instring to have room
271  * for the expansion. Every byte that is converted is replaced by three ASCII
272  * characters.
273  *
274  * \param string string to be converted
275  * \param outbuf resulting encoded string
276  * \param buflen size of output buffer
277  * \param spec flags describing how the encoding should be performed
278  * \return a pointer to the uri encoded string
279  */
280 char *ast_uri_encode(const char *string, char *outbuf, int buflen, struct ast_flags spec);
281
282 /*!
283  * \brief Decode URI, URN, URL (overwrite string)
284  *
285  * \note The ast_uri_http_legacy decode spec flag will cause this function to
286  * decode '+' as ' '.
287  *
288  * \param s string to be decoded
289  * \param spec flags describing how the decoding should be performed
290  */
291 void ast_uri_decode(char *s, struct ast_flags spec);
292
293 /*!
294  * \brief Escape characters found in a quoted string.
295  *
296  * \note This function escapes quoted characters based on the 'qdtext' set of
297  * allowed characters from RFC 3261 section 25.1.
298  *
299  * \param string string to be escaped
300  * \param outbuf resulting escaped string
301  * \param buflen size of output buffer
302  * \return a pointer to the escaped string
303  */
304 char *ast_escape_quoted(const char *string, char *outbuf, int buflen);
305
306 static force_inline void ast_slinear_saturated_add(short *input, short *value)
307 {
308         int res;
309
310         res = (int) *input + *value;
311         if (res > 32767)
312                 *input = 32767;
313         else if (res < -32767)
314                 *input = -32767;
315         else
316                 *input = (short) res;
317 }
318
319 static force_inline void ast_slinear_saturated_subtract(short *input, short *value)
320 {
321         int res;
322
323         res = (int) *input - *value;
324         if (res > 32767)
325                 *input = 32767;
326         else if (res < -32767)
327                 *input = -32767;
328         else
329                 *input = (short) res;
330 }
331
332 static force_inline void ast_slinear_saturated_multiply(short *input, short *value)
333 {
334         int res;
335
336         res = (int) *input * *value;
337         if (res > 32767)
338                 *input = 32767;
339         else if (res < -32767)
340                 *input = -32767;
341         else
342                 *input = (short) res;
343 }
344
345 static force_inline void ast_slinear_saturated_divide(short *input, short *value)
346 {
347         *input /= *value;
348 }
349
350 #ifdef localtime_r
351 #undef localtime_r
352 #endif
353 #define localtime_r __dont_use_localtime_r_use_ast_localtime_instead__
354
355 int ast_utils_init(void);
356 int ast_wait_for_input(int fd, int ms);
357
358 /*!
359  * \brief Try to write string, but wait no more than ms milliseconds
360  * before timing out.
361  *
362  * \note If you are calling ast_carefulwrite, it is assumed that you are calling
363  * it on a file descriptor that _DOES_ have NONBLOCK set.  This way,
364  * there is only one system call made to do a write, unless we actually
365  * have a need to wait.  This way, we get better performance.
366  */
367 int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
368
369 /*!
370  * \brief Write data to a file stream with a timeout
371  *
372  * \param f the file stream to write to
373  * \param fd the file description to poll on to know when the file stream can
374  *        be written to without blocking.
375  * \param s the buffer to write from
376  * \param len the number of bytes to write
377  * \param timeoutms The maximum amount of time to block in this function trying
378  *        to write, specified in milliseconds.
379  *
380  * \note This function assumes that the associated file stream has been set up
381  *       as non-blocking.
382  *
383  * \retval 0 success
384  * \retval -1 error
385  */
386 int ast_careful_fwrite(FILE *f, int fd, const char *s, size_t len, int timeoutms);
387
388 /*
389  * Thread management support (should be moved to lock.h or a different header)
390  */
391
392 #define AST_STACKSIZE (((sizeof(void *) * 8 * 8) - 16) * 1024)
393
394 #if defined(LOW_MEMORY)
395 #define AST_BACKGROUND_STACKSIZE (((sizeof(void *) * 8 * 2) - 16) * 1024)
396 #else
397 #define AST_BACKGROUND_STACKSIZE AST_STACKSIZE
398 #endif
399
400 void ast_register_thread(char *name);
401 void ast_unregister_thread(void *id);
402
403 int ast_pthread_create_stack(pthread_t *thread, pthread_attr_t *attr, void *(*start_routine)(void *),
404                              void *data, size_t stacksize, const char *file, const char *caller,
405                              int line, const char *start_fn);
406
407 int ast_pthread_create_detached_stack(pthread_t *thread, pthread_attr_t *attr, void*(*start_routine)(void *),
408                                  void *data, size_t stacksize, const char *file, const char *caller,
409                                  int line, const char *start_fn);
410
411 #define ast_pthread_create(a, b, c, d)                          \
412         ast_pthread_create_stack(a, b, c, d,                    \
413                 0, __FILE__, __FUNCTION__, __LINE__, #c)
414
415 #define ast_pthread_create_detached(a, b, c, d)                 \
416         ast_pthread_create_detached_stack(a, b, c, d,           \
417                 0, __FILE__, __FUNCTION__, __LINE__, #c)
418
419 #define ast_pthread_create_background(a, b, c, d)               \
420         ast_pthread_create_stack(a, b, c, d,                    \
421                 AST_BACKGROUND_STACKSIZE,                       \
422                 __FILE__, __FUNCTION__, __LINE__, #c)
423
424 #define ast_pthread_create_detached_background(a, b, c, d)      \
425         ast_pthread_create_detached_stack(a, b, c, d,           \
426                 AST_BACKGROUND_STACKSIZE,                       \
427                 __FILE__, __FUNCTION__, __LINE__, #c)
428
429 /* End of thread management support */
430
431 /*!
432  * \brief Replace '^' in a string with ','
433  * \param s String within which to replace characters
434  */
435 void ast_replace_subargument_delimiter(char *s);
436
437 /*!
438  * \brief Process a string to find and replace characters
439  * \param start The string to analyze
440  * \param find The character to find
441  * \param replace_with The character that will replace the one we are looking for
442  */
443 char *ast_process_quotes_and_slashes(char *start, char find, char replace_with);
444
445 long int ast_random(void);
446
447
448 /*!
449  * \brief free() wrapper
450  *
451  * ast_free_ptr should be used when a function pointer for free() needs to be passed
452  * as the argument to a function. Otherwise, astmm will cause seg faults.
453  */
454 #ifdef __AST_DEBUG_MALLOC
455 static void ast_free_ptr(void *ptr) attribute_unused;
456 static void ast_free_ptr(void *ptr)
457 {
458         ast_free(ptr);
459 }
460 #else
461 #define ast_free free
462 #define ast_free_ptr ast_free
463 #endif
464
465 #ifndef __AST_DEBUG_MALLOC
466
467 #define MALLOC_FAILURE_MSG \
468         ast_log(LOG_ERROR, "Memory Allocation Failure in function %s at line %d of %s\n", func, lineno, file);
469 /*!
470  * \brief A wrapper for malloc()
471  *
472  * ast_malloc() is a wrapper for malloc() that will generate an Asterisk log
473  * message in the case that the allocation fails.
474  *
475  * The argument and return value are the same as malloc()
476  */
477 #define ast_malloc(len) \
478         _ast_malloc((len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
479
480 AST_INLINE_API(
481 void * attribute_malloc _ast_malloc(size_t len, const char *file, int lineno, const char *func),
482 {
483         void *p;
484
485         if (!(p = malloc(len)))
486                 MALLOC_FAILURE_MSG;
487
488         return p;
489 }
490 )
491
492 /*!
493  * \brief A wrapper for calloc()
494  *
495  * ast_calloc() is a wrapper for calloc() that will generate an Asterisk log
496  * message in the case that the allocation fails.
497  *
498  * The arguments and return value are the same as calloc()
499  */
500 #define ast_calloc(num, len) \
501         _ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
502
503 AST_INLINE_API(
504 void * attribute_malloc _ast_calloc(size_t num, size_t len, const char *file, int lineno, const char *func),
505 {
506         void *p;
507
508         if (!(p = calloc(num, len)))
509                 MALLOC_FAILURE_MSG;
510
511         return p;
512 }
513 )
514
515 /*!
516  * \brief A wrapper for calloc() for use in cache pools
517  *
518  * ast_calloc_cache() is a wrapper for calloc() that will generate an Asterisk log
519  * message in the case that the allocation fails. When memory debugging is in use,
520  * the memory allocated by this function will be marked as 'cache' so it can be
521  * distinguished from normal memory allocations.
522  *
523  * The arguments and return value are the same as calloc()
524  */
525 #define ast_calloc_cache(num, len) \
526         _ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
527
528 /*!
529  * \brief A wrapper for realloc()
530  *
531  * ast_realloc() is a wrapper for realloc() that will generate an Asterisk log
532  * message in the case that the allocation fails.
533  *
534  * The arguments and return value are the same as realloc()
535  */
536 #define ast_realloc(p, len) \
537         _ast_realloc((p), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
538
539 AST_INLINE_API(
540 void * attribute_malloc _ast_realloc(void *p, size_t len, const char *file, int lineno, const char *func),
541 {
542         void *newp;
543
544         if (!(newp = realloc(p, len)))
545                 MALLOC_FAILURE_MSG;
546
547         return newp;
548 }
549 )
550
551 /*!
552  * \brief A wrapper for strdup()
553  *
554  * ast_strdup() is a wrapper for strdup() that will generate an Asterisk log
555  * message in the case that the allocation fails.
556  *
557  * ast_strdup(), unlike strdup(), can safely accept a NULL argument. If a NULL
558  * argument is provided, ast_strdup will return NULL without generating any
559  * kind of error log message.
560  *
561  * The argument and return value are the same as strdup()
562  */
563 #define ast_strdup(str) \
564         _ast_strdup((str), __FILE__, __LINE__, __PRETTY_FUNCTION__)
565
566 AST_INLINE_API(
567 char * attribute_malloc _ast_strdup(const char *str, const char *file, int lineno, const char *func),
568 {
569         char *newstr = NULL;
570
571         if (str) {
572                 if (!(newstr = strdup(str)))
573                         MALLOC_FAILURE_MSG;
574         }
575
576         return newstr;
577 }
578 )
579
580 /*!
581  * \brief A wrapper for strndup()
582  *
583  * ast_strndup() is a wrapper for strndup() that will generate an Asterisk log
584  * message in the case that the allocation fails.
585  *
586  * ast_strndup(), unlike strndup(), can safely accept a NULL argument for the
587  * string to duplicate. If a NULL argument is provided, ast_strdup will return
588  * NULL without generating any kind of error log message.
589  *
590  * The arguments and return value are the same as strndup()
591  */
592 #define ast_strndup(str, len) \
593         _ast_strndup((str), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
594
595 AST_INLINE_API(
596 char * attribute_malloc _ast_strndup(const char *str, size_t len, const char *file, int lineno, const char *func),
597 {
598         char *newstr = NULL;
599
600         if (str) {
601                 if (!(newstr = strndup(str, len)))
602                         MALLOC_FAILURE_MSG;
603         }
604
605         return newstr;
606 }
607 )
608
609 /*!
610  * \brief A wrapper for asprintf()
611  *
612  * ast_asprintf() is a wrapper for asprintf() that will generate an Asterisk log
613  * message in the case that the allocation fails.
614  *
615  * The arguments and return value are the same as asprintf()
616  */
617 #define ast_asprintf(ret, fmt, ...) \
618         _ast_asprintf((ret), __FILE__, __LINE__, __PRETTY_FUNCTION__, fmt, __VA_ARGS__)
619
620 int __attribute__((format(printf, 5, 6)))
621         _ast_asprintf(char **ret, const char *file, int lineno, const char *func, const char *fmt, ...);
622
623 /*!
624  * \brief A wrapper for vasprintf()
625  *
626  * ast_vasprintf() is a wrapper for vasprintf() that will generate an Asterisk log
627  * message in the case that the allocation fails.
628  *
629  * The arguments and return value are the same as vasprintf()
630  */
631 #define ast_vasprintf(ret, fmt, ap) \
632         _ast_vasprintf((ret), __FILE__, __LINE__, __PRETTY_FUNCTION__, (fmt), (ap))
633
634 AST_INLINE_API(
635 __attribute__((format(printf, 5, 0)))
636 int _ast_vasprintf(char **ret, const char *file, int lineno, const char *func, const char *fmt, va_list ap),
637 {
638         int res;
639
640         if ((res = vasprintf(ret, fmt, ap)) == -1)
641                 MALLOC_FAILURE_MSG;
642
643         return res;
644 }
645 )
646
647 #endif /* AST_DEBUG_MALLOC */
648
649 /*!
650   \brief call __builtin_alloca to ensure we get gcc builtin semantics
651   \param size The size of the buffer we want allocated
652
653   This macro will attempt to allocate memory from the stack.  If it fails
654   you won't get a NULL returned, but a SEGFAULT if you're lucky.
655 */
656 #define ast_alloca(size) __builtin_alloca(size)
657
658 #if !defined(ast_strdupa) && defined(__GNUC__)
659 /*!
660  * \brief duplicate a string in memory from the stack
661  * \param s The string to duplicate
662  *
663  * This macro will duplicate the given string.  It returns a pointer to the stack
664  * allocatted memory for the new string.
665  */
666 #define ast_strdupa(s)                                                    \
667         (__extension__                                                    \
668         ({                                                                \
669                 const char *__old = (s);                                  \
670                 size_t __len = strlen(__old) + 1;                         \
671                 char *__new = __builtin_alloca(__len);                    \
672                 memcpy (__new, __old, __len);                             \
673                 __new;                                                    \
674         }))
675 #endif
676
677 /*!
678  * \brief Disable PMTU discovery on a socket
679  * \param sock The socket to manipulate
680  * \return Nothing
681  *
682  * On Linux, UDP sockets default to sending packets with the Dont Fragment (DF)
683  * bit set. This is supposedly done to allow the application to do PMTU
684  * discovery, but Asterisk does not do this.
685  *
686  * Because of this, UDP packets sent by Asterisk that are larger than the MTU
687  * of any hop in the path will be lost. This function can be called on a socket
688  * to ensure that the DF bit will not be set.
689  */
690 void ast_enable_packet_fragmentation(int sock);
691
692 /*!
693  * \brief Recursively create directory path
694  * \param path The directory path to create
695  * \param mode The permissions with which to try to create the directory
696  * \return 0 on success or an error code otherwise
697  *
698  * Creates a directory path, creating parent directories as needed.
699  */
700 int ast_mkdir(const char *path, int mode);
701
702 #define ARRAY_LEN(a) (size_t) (sizeof(a) / sizeof(0[a]))
703
704
705 /* Definition for Digest authorization */
706 struct ast_http_digest {
707         AST_DECLARE_STRING_FIELDS(
708                 AST_STRING_FIELD(username);
709                 AST_STRING_FIELD(nonce);
710                 AST_STRING_FIELD(uri);
711                 AST_STRING_FIELD(realm);
712                 AST_STRING_FIELD(domain);
713                 AST_STRING_FIELD(response);
714                 AST_STRING_FIELD(cnonce);
715                 AST_STRING_FIELD(opaque);
716                 AST_STRING_FIELD(nc);
717         );
718         int qop;                /* Flag set to 1, if we send/recv qop="quth" */
719 };
720
721 /*!
722  * \brief Parse digest authorization header.
723  * \return Returns -1 if we have no auth or something wrong with digest.
724  * \note This function may be used for Digest request and responce header.
725  * request arg is set to nonzero, if we parse Digest Request.
726  * pedantic arg can be set to nonzero if we need to do addition Digest check.
727  */
728 int ast_parse_digest(const char *digest, struct ast_http_digest *d, int request, int pedantic);
729
730
731 #ifdef AST_DEVMODE
732 #define ast_assert(a) _ast_assert(a, # a, __FILE__, __LINE__, __PRETTY_FUNCTION__)
733 static void force_inline _ast_assert(int condition, const char *condition_str,
734         const char *file, int line, const char *function)
735 {
736         if (__builtin_expect(!condition, 1)) {
737                 /* Attempt to put it into the logger, but hope that at least someone saw the
738                  * message on stderr ... */
739                 ast_log(__LOG_ERROR, file, line, function, "FRACK!, Failed assertion %s (%d)\n",
740                         condition_str, condition);
741                 fprintf(stderr, "FRACK!, Failed assertion %s (%d) at line %d in %s of %s\n",
742                         condition_str, condition, line, function, file);
743                 /* Give the logger a chance to get the message out, just in case we abort(), or
744                  * Asterisk crashes due to whatever problem just happened after we exit ast_assert(). */
745                 usleep(1);
746 #ifdef DO_CRASH
747                 abort();
748                 /* Just in case abort() doesn't work or something else super silly,
749                  * and for Qwell's amusement. */
750                 *((int*)0)=0;
751 #endif
752         }
753 }
754 #else
755 #define ast_assert(a)
756 #endif
757
758 #include "asterisk/strings.h"
759
760 /*!
761  * \brief Return the number of bytes used in the alignment of type.
762  * \param type
763  * \return The number of bytes required for alignment.
764  *
765  * This is really just __alignof__(), but tucked away in this header so we
766  * don't have to look at the nasty underscores in the source.
767  */
768 #define ast_alignof(type) __alignof__(type)
769
770 /*!
771  * \brief Increase offset so it is a multiple of the required alignment of type.
772  * \param offset The value that should be increased.
773  * \param type The data type that offset should be aligned to.
774  * \return The smallest multiple of alignof(type) larger than or equal to offset.
775  * \see ast_make_room_for()
776  *
777  * Many systems prefer integers to be stored on aligned on memory locations.
778  * This macro will increase an offset so a value of the supplied type can be
779  * safely be stored on such a memory location.
780  *
781  * Examples:
782  * ast_align_for(0x17, int64_t) ==> 0x18
783  * ast_align_for(0x18, int64_t) ==> 0x18
784  * ast_align_for(0x19, int64_t) ==> 0x20
785  *
786  * Don't mind the ugliness, the compiler will optimize it.
787  */
788 #define ast_align_for(offset, type) (((offset + __alignof__(type) - 1) / __alignof__(type)) * __alignof__(type))
789
790 /*!
791  * \brief Increase offset by the required alignment of type and make sure it is
792  *        a multiple of said alignment.
793  * \param offset The value that should be increased.
794  * \param type The data type that room should be reserved for.
795  * \return The smallest multiple of alignof(type) larger than or equal to offset
796  *         plus alignof(type).
797  * \see ast_align_for()
798  *
799  * A use case for this is when prepending length fields of type int to a buffer.
800  * If you keep the offset a multiple of the alignment of the integer type,
801  * a next block of length+buffer will have the length field automatically
802  * aligned.
803  *
804  * Examples:
805  * ast_make_room_for(0x17, int64_t) ==> 0x20
806  * ast_make_room_for(0x18, int64_t) ==> 0x20
807  * ast_make_room_for(0x19, int64_t) ==> 0x28
808  *
809  * Don't mind the ugliness, the compiler will optimize it.
810  */
811 #define ast_make_room_for(offset, type) (((offset + (2 * __alignof__(type) - 1)) / __alignof__(type)) * __alignof__(type))
812
813 /*!
814  * \brief An Entity ID is essentially a MAC address, brief and unique
815  */
816 struct ast_eid {
817         unsigned char eid[6];
818 } __attribute__((__packed__));
819
820 /*!
821  * \brief Global EID
822  *
823  * This is set in asterisk.conf, or determined automatically by taking the mac
824  * address of an Ethernet interface on the system.
825  */
826 extern struct ast_eid ast_eid_default;
827
828 /*!
829  * \brief Fill in an ast_eid with the default eid of this machine
830  * \since 1.6.1
831  */
832 void ast_set_default_eid(struct ast_eid *eid);
833
834 /*!
835  * \brief Convert an EID to a string
836  * \since 1.6.1
837  */
838 char *ast_eid_to_str(char *s, int maxlen, struct ast_eid *eid);
839
840 /*!
841  * \brief Convert a string into an EID
842  *
843  * This function expects an EID in the format:
844  *    00:11:22:33:44:55
845  *
846  * \return 0 success, non-zero failure
847  * \since 1.6.1
848  */
849 int ast_str_to_eid(struct ast_eid *eid, const char *s);
850
851 /*!
852  * \brief Compare two EIDs
853  *
854  * \return 0 if the two are the same, non-zero otherwise
855  * \since 1.6.1
856  */
857 int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2);
858
859 /*!
860  * \brief Get current thread ID
861  * \return the ID if platform is supported, else -1
862  */
863 int ast_get_tid(void);
864
865 /*!
866  * \brief Resolve a binary to a full pathname
867  * \param binary Name of the executable to resolve
868  * \param fullpath Buffer to hold the complete pathname
869  * \param fullpath_size Size of \a fullpath
870  * \retval NULL \a binary was not found or the environment variable PATH is not set
871  * \return \a fullpath
872  */
873 char *ast_utils_which(const char *binary, char *fullpath, size_t fullpath_size);
874
875 /*!
876  * \brief Declare a variable that will call a destructor function when it goes out of scope.
877  *
878  * Resource Allocation Is Initialization (RAII) variable declaration.
879  *
880  * \since 11.0
881  * \param vartype The type of the variable
882  * \param varname The name of the variable
883  * \param initval The initial value of the variable
884  * \param dtor The destructor function of type' void func(vartype *)'
885  *
886  * \code
887  * void mything_cleanup(struct mything *t)
888  * {
889  *     if (t) {
890  *         ast_free(t->stuff);
891  *     }
892  * }
893  *
894  * void do_stuff(const char *name)
895  * {
896  *     RAII_VAR(struct mything *, thing, mything_alloc(name), mything_cleanup);
897  *     ...
898  * }
899  * \endcode
900  *
901  * \note This macro is especially useful for working with ao2 objects. A common idiom
902  * would be a function that needed to look up an ao2 object and might have several error
903  * conditions after the allocation that would normally need to unref the ao2 object.
904  * With RAII_VAR, it is possible to just return and leave the cleanup to the destructor
905  * function. For example:
906  *
907  * \code
908  * void do_stuff(const char *name)
909  * {
910  *     RAII_VAR(struct mything *, thing, find_mything(name), ao2_cleanup);
911  *     if (!thing) {
912  *         return;
913  *     }
914  *     if (error) {
915  *         return;
916  *     }
917  *     do_stuff_with_thing(thing);
918  * }
919  * \endcode
920  */
921 #define RAII_VAR(vartype, varname, initval, dtor) \
922     auto void _dtor_ ## varname (vartype * v); \
923     auto void _dtor_ ## varname (vartype * v) { dtor(*v); } \
924     vartype varname __attribute__((cleanup(_dtor_ ## varname))) = (initval)
925
926 #endif /* _ASTERISK_UTILS_H */