core: Remove ABI effects of MALLOC_DEBUG.
[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 /*! ast_xml_escape
294         \brief Escape reserved characters for use in XML.
295
296         If \a outbuf is too short, the output string will be truncated.
297         Regardless, the output will always be null terminated.
298
299         \param string String to be converted
300         \param outbuf Resulting encoded string
301         \param buflen Size of output buffer
302         \return 0 for success
303         \return -1 if buflen is too short.
304  */
305 int ast_xml_escape(const char *string, char *outbuf, size_t buflen);
306
307 /*!
308  * \brief Escape characters found in a quoted string.
309  *
310  * \note This function escapes quoted characters based on the 'qdtext' set of
311  * allowed characters from RFC 3261 section 25.1.
312  *
313  * \param string string to be escaped
314  * \param outbuf resulting escaped string
315  * \param buflen size of output buffer
316  * \return a pointer to the escaped string
317  */
318 char *ast_escape_quoted(const char *string, char *outbuf, int buflen);
319
320 /*!
321  * \brief Escape semicolons found in a string.
322  *
323  * \param string string to be escaped
324  * \param outbuf resulting escaped string
325  * \param buflen size of output buffer
326  * \return a pointer to the escaped string
327  */
328 char *ast_escape_semicolons(const char *string, char *outbuf, int buflen);
329
330 /*!
331  * \brief Unescape quotes in a string
332  *
333  * \param quote_str The string with quotes to be unescaped
334  *
335  * \note This function mutates the passed-in string.
336  */
337 void ast_unescape_quoted(char *quote_str);
338
339 static force_inline void ast_slinear_saturated_add(short *input, short *value)
340 {
341         int res;
342
343         res = (int) *input + *value;
344         if (res > 32767)
345                 *input = 32767;
346         else if (res < -32768)
347                 *input = -32768;
348         else
349                 *input = (short) res;
350 }
351
352 static force_inline void ast_slinear_saturated_subtract(short *input, short *value)
353 {
354         int res;
355
356         res = (int) *input - *value;
357         if (res > 32767)
358                 *input = 32767;
359         else if (res < -32768)
360                 *input = -32768;
361         else
362                 *input = (short) res;
363 }
364
365 static force_inline void ast_slinear_saturated_multiply(short *input, short *value)
366 {
367         int res;
368
369         res = (int) *input * *value;
370         if (res > 32767)
371                 *input = 32767;
372         else if (res < -32768)
373                 *input = -32768;
374         else
375                 *input = (short) res;
376 }
377
378 static force_inline void ast_slinear_saturated_divide(short *input, short *value)
379 {
380         *input /= *value;
381 }
382
383 #ifdef localtime_r
384 #undef localtime_r
385 #endif
386 #define localtime_r __dont_use_localtime_r_use_ast_localtime_instead__
387
388 int ast_utils_init(void);
389 int ast_wait_for_input(int fd, int ms);
390 int ast_wait_for_output(int fd, int ms);
391
392 /*!
393  * \brief Try to write string, but wait no more than ms milliseconds
394  * before timing out.
395  *
396  * \note If you are calling ast_carefulwrite, it is assumed that you are calling
397  * it on a file descriptor that _DOES_ have NONBLOCK set.  This way,
398  * there is only one system call made to do a write, unless we actually
399  * have a need to wait.  This way, we get better performance.
400  */
401 int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
402
403 /*!
404  * \brief Write data to a file stream with a timeout
405  *
406  * \param f the file stream to write to
407  * \param fd the file description to poll on to know when the file stream can
408  *        be written to without blocking.
409  * \param s the buffer to write from
410  * \param len the number of bytes to write
411  * \param timeoutms The maximum amount of time to block in this function trying
412  *        to write, specified in milliseconds.
413  *
414  * \note This function assumes that the associated file stream has been set up
415  *       as non-blocking.
416  *
417  * \retval 0 success
418  * \retval -1 error
419  */
420 int ast_careful_fwrite(FILE *f, int fd, const char *s, size_t len, int timeoutms);
421
422 /*
423  * Thread management support (should be moved to lock.h or a different header)
424  */
425
426 #define AST_STACKSIZE     (((sizeof(void *) * 8 * 8) - 16) * 1024)
427 #define AST_STACKSIZE_LOW (((sizeof(void *) * 8 * 2) - 16) * 1024)
428
429 int ast_background_stacksize(void);
430
431 #define AST_BACKGROUND_STACKSIZE ast_background_stacksize()
432
433 void ast_register_thread(char *name);
434 void ast_unregister_thread(void *id);
435
436 int ast_pthread_create_stack(pthread_t *thread, pthread_attr_t *attr, void *(*start_routine)(void *),
437                              void *data, size_t stacksize, const char *file, const char *caller,
438                              int line, const char *start_fn);
439
440 int ast_pthread_create_detached_stack(pthread_t *thread, pthread_attr_t *attr, void*(*start_routine)(void *),
441                                  void *data, size_t stacksize, const char *file, const char *caller,
442                                  int line, const char *start_fn);
443
444 #define ast_pthread_create(a, b, c, d)                          \
445         ast_pthread_create_stack(a, b, c, d,                    \
446                 0, __FILE__, __FUNCTION__, __LINE__, #c)
447
448 #define ast_pthread_create_detached(a, b, c, d)                 \
449         ast_pthread_create_detached_stack(a, b, c, d,           \
450                 0, __FILE__, __FUNCTION__, __LINE__, #c)
451
452 #define ast_pthread_create_background(a, b, c, d)               \
453         ast_pthread_create_stack(a, b, c, d,                    \
454                 AST_BACKGROUND_STACKSIZE,                       \
455                 __FILE__, __FUNCTION__, __LINE__, #c)
456
457 #define ast_pthread_create_detached_background(a, b, c, d)      \
458         ast_pthread_create_detached_stack(a, b, c, d,           \
459                 AST_BACKGROUND_STACKSIZE,                       \
460                 __FILE__, __FUNCTION__, __LINE__, #c)
461
462 /* End of thread management support */
463
464 /*!
465  * \brief Replace '^' in a string with ','
466  * \param s String within which to replace characters
467  */
468 void ast_replace_subargument_delimiter(char *s);
469
470 /*!
471  * \brief Process a string to find and replace characters
472  * \param start The string to analyze
473  * \param find The character to find
474  * \param replace_with The character that will replace the one we are looking for
475  */
476 char *ast_process_quotes_and_slashes(char *start, char find, char replace_with);
477
478 long int ast_random(void);
479
480 /*!
481  * \brief Returns a random number between 0.0 and 1.0, inclusive.
482  * \since 12
483  */
484 #define ast_random_double() (((double)ast_random()) / RAND_MAX)
485
486 /*!
487  * \brief DEBUG_CHAOS returns failure randomly
488  *
489  * DEBUG_CHAOS_RETURN(failure); can be used to fake
490  * failure of functions such as memory allocation,
491  * for the purposes of testing failure handling.
492  */
493 #ifdef DEBUG_CHAOS
494 #ifndef DEBUG_CHAOS_ALLOC_CHANCE
495 #define DEBUG_CHAOS_ALLOC_CHANCE 100000
496 #endif
497 /* Could #define DEBUG_CHAOS_ENABLE ast_fully_booted */
498 #ifndef DEBUG_CHAOS_ENABLE
499 #define DEBUG_CHAOS_ENABLE 1
500 #endif
501 #define DEBUG_CHAOS_RETURN(CHANCE, FAILURE) \
502         do { \
503                 if ((DEBUG_CHAOS_ENABLE) && (ast_random() % CHANCE == 0)) { \
504                         return FAILURE; \
505                 } \
506         } while (0)
507 #else
508 #define DEBUG_CHAOS_RETURN(c,f)
509 #endif
510
511
512 #if !defined(NO_MALLOC_DEBUG) && !defined(STANDALONE) && !defined(STANDALONE2)
513 void *ast_std_malloc(size_t size);
514 void *ast_std_calloc(size_t nmemb, size_t size);
515 void *ast_std_realloc(void *ptr, size_t size);
516 void ast_std_free(void *ptr);
517
518 /*!
519  * \brief free() wrapper
520  *
521  * ast_free_ptr should be used when a function pointer for free() needs to be passed
522  * as the argument to a function. Otherwise, astmm will cause seg faults.
523  */
524 void ast_free_ptr(void *ptr);
525 void __ast_free(void *ptr, const char *file, int lineno, const char *func);
526
527 #else
528
529 /*
530  * Need to defeat the MALLOC_DEBUG API when building the standalone utilities.
531  */
532
533 #define ast_std_malloc malloc
534 #define ast_std_calloc calloc
535 #define ast_std_realloc realloc
536 #define ast_std_free free
537
538 #define ast_free_ptr free
539 #define ast_free free
540
541 #define __ast_repl_calloc(nmemb, size, file, lineno, func) \
542         calloc(nmemb, size)
543
544 #define __ast_repl_calloc_cache(nmemb, size, file, lineno, func) \
545         calloc(nmemb, size)
546
547 #define __ast_repl_malloc(size, file, lineno, func) \
548         malloc(size)
549
550 #define __ast_repl_realloc(ptr, size, file, lineno, func) \
551         realloc(ptr, size)
552
553 #define __ast_repl_strdup(s, file, lineno, func) \
554         strdup(s)
555
556 #define __ast_repl_strndup(s, n, file, lineno, func) \
557         strndup(s, n)
558
559 #define __ast_repl_vasprintf(strp, format, ap, file, lineno, func) \
560         vasprintf(strp, format, ap)
561 #endif
562
563 #if defined(AST_IN_CORE)
564 #define MALLOC_FAILURE_MSG \
565         ast_log_safe(LOG_ERROR, "Memory Allocation Failure in function %s at line %d of %s\n", func, lineno, file)
566 #else
567 #define MALLOC_FAILURE_MSG \
568         ast_log(LOG_ERROR, "Memory Allocation Failure in function %s at line %d of %s\n", func, lineno, file)
569 #endif
570
571 AST_INLINE_API(
572 void * attribute_malloc __ast_malloc(size_t len, const char *file, int lineno, const char *func),
573 {
574         void *p;
575
576         DEBUG_CHAOS_RETURN(DEBUG_CHAOS_ALLOC_CHANCE, NULL);
577
578         p = __ast_repl_malloc(len, file, lineno, func);
579         if (!p) {
580                 MALLOC_FAILURE_MSG;
581         }
582
583         return p;
584 }
585 )
586
587 AST_INLINE_API(
588 void * attribute_malloc __ast_calloc(size_t num, size_t len, const char *file, int lineno, const char *func),
589 {
590         void *p;
591
592         DEBUG_CHAOS_RETURN(DEBUG_CHAOS_ALLOC_CHANCE, NULL);
593
594         p = __ast_repl_calloc(num, len, file, lineno, func);
595         if (!p) {
596                 MALLOC_FAILURE_MSG;
597         }
598
599         return p;
600 }
601 )
602
603 AST_INLINE_API(
604 void * attribute_malloc __ast_calloc_cache(size_t num, size_t len, const char *file, int lineno, const char *func),
605 {
606         void *p;
607
608         DEBUG_CHAOS_RETURN(DEBUG_CHAOS_ALLOC_CHANCE, NULL);
609
610         p = __ast_repl_calloc_cache(num, len, file, lineno, func);
611         if (!p) {
612                 MALLOC_FAILURE_MSG;
613         }
614
615         return p;
616 }
617 )
618
619 AST_INLINE_API(
620 void * attribute_malloc __ast_realloc(void *p, size_t len, const char *file, int lineno, const char *func),
621 {
622         void *newp;
623
624         DEBUG_CHAOS_RETURN(DEBUG_CHAOS_ALLOC_CHANCE, NULL);
625
626         newp = __ast_repl_realloc(p, len, file, lineno, func);
627         if (!newp) {
628                 MALLOC_FAILURE_MSG;
629         }
630
631         return newp;
632 }
633 )
634
635 AST_INLINE_API(
636 char * attribute_malloc __ast_strdup(const char *str, const char *file, int lineno, const char *func),
637 {
638         char *newstr = NULL;
639
640         DEBUG_CHAOS_RETURN(DEBUG_CHAOS_ALLOC_CHANCE, NULL);
641
642         if (str) {
643                 newstr = __ast_repl_strdup(str, file, lineno, func);
644                 if (!newstr) {
645                         MALLOC_FAILURE_MSG;
646                 }
647         }
648
649         return newstr;
650 }
651 )
652
653 AST_INLINE_API(
654 char * attribute_malloc __ast_strndup(const char *str, size_t len, const char *file, int lineno, const char *func),
655 {
656         char *newstr = NULL;
657
658         DEBUG_CHAOS_RETURN(DEBUG_CHAOS_ALLOC_CHANCE, NULL);
659
660         if (str) {
661                 newstr = __ast_repl_strndup(str, len, file, lineno, func);
662                 if (!newstr) {
663                         MALLOC_FAILURE_MSG;
664                 }
665         }
666
667         return newstr;
668 }
669 )
670
671 AST_INLINE_API(
672 __attribute__((format(printf, 5, 6)))
673 int __ast_asprintf(const char *file, int lineno, const char *func, char **ret, const char *fmt, ...),
674 {
675         int res;
676         va_list ap;
677
678         DEBUG_CHAOS_RETURN(DEBUG_CHAOS_ALLOC_CHANCE, -1);
679
680         va_start(ap, fmt);
681         res = __ast_repl_vasprintf(ret, fmt, ap, file, lineno, func);
682         if (res < 0) {
683                 /*
684                  * *ret is undefined so set to NULL to ensure it is
685                  * initialized to something useful.
686                  */
687                 *ret = NULL;
688                 MALLOC_FAILURE_MSG;
689         }
690         va_end(ap);
691
692         return res;
693 }
694 )
695
696 AST_INLINE_API(
697 __attribute__((format(printf, 2, 0)))
698 int __ast_vasprintf(char **ret, const char *fmt, va_list ap, const char *file, int lineno, const char *func),
699 {
700         int res;
701
702         DEBUG_CHAOS_RETURN(DEBUG_CHAOS_ALLOC_CHANCE, -1);
703
704         res = __ast_repl_vasprintf(ret, fmt, ap, file, lineno, func);
705         if (res < 0) {
706                 /*
707                  * *ret is undefined so set to NULL to ensure it is
708                  * initialized to something useful.
709                  */
710                 *ret = NULL;
711                 MALLOC_FAILURE_MSG;
712         }
713
714         return res;
715 }
716 )
717
718 /*!
719  * \brief A wrapper for malloc()
720  *
721  * ast_malloc() is a wrapper for malloc() that will generate an Asterisk log
722  * message in the case that the allocation fails.
723  *
724  * The argument and return value are the same as malloc()
725  */
726 #define ast_malloc(len) \
727         __ast_malloc((len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
728
729 /*!
730  * \brief A wrapper for calloc()
731  *
732  * ast_calloc() is a wrapper for calloc() that will generate an Asterisk log
733  * message in the case that the allocation fails.
734  *
735  * The arguments and return value are the same as calloc()
736  */
737 #define ast_calloc(num, len) \
738         __ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
739
740 /*!
741  * \brief A wrapper for calloc() for use in cache pools
742  *
743  * ast_calloc_cache() is a wrapper for calloc() that will generate an Asterisk log
744  * message in the case that the allocation fails. When memory debugging is in use,
745  * the memory allocated by this function will be marked as 'cache' so it can be
746  * distinguished from normal memory allocations.
747  *
748  * The arguments and return value are the same as calloc()
749  */
750 #define ast_calloc_cache(num, len) \
751         __ast_calloc_cache((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
752
753 /*!
754  * \brief A wrapper for realloc()
755  *
756  * ast_realloc() is a wrapper for realloc() that will generate an Asterisk log
757  * message in the case that the allocation fails.
758  *
759  * The arguments and return value are the same as realloc()
760  */
761 #define ast_realloc(p, len) \
762         __ast_realloc((p), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
763
764 /*!
765  * \brief A wrapper for strdup()
766  *
767  * ast_strdup() is a wrapper for strdup() that will generate an Asterisk log
768  * message in the case that the allocation fails.
769  *
770  * ast_strdup(), unlike strdup(), can safely accept a NULL argument. If a NULL
771  * argument is provided, ast_strdup will return NULL without generating any
772  * kind of error log message.
773  *
774  * The argument and return value are the same as strdup()
775  */
776 #define ast_strdup(str) \
777         __ast_strdup((str), __FILE__, __LINE__, __PRETTY_FUNCTION__)
778
779 /*!
780  * \brief A wrapper for strndup()
781  *
782  * ast_strndup() is a wrapper for strndup() that will generate an Asterisk log
783  * message in the case that the allocation fails.
784  *
785  * ast_strndup(), unlike strndup(), can safely accept a NULL argument for the
786  * string to duplicate. If a NULL argument is provided, ast_strdup will return
787  * NULL without generating any kind of error log message.
788  *
789  * The arguments and return value are the same as strndup()
790  */
791 #define ast_strndup(str, len) \
792         __ast_strndup((str), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
793
794 /*!
795  * \brief A wrapper for asprintf()
796  *
797  * ast_asprintf() is a wrapper for asprintf() that will generate an Asterisk log
798  * message in the case that the allocation fails.
799  *
800  * The arguments and return value are the same as asprintf()
801  */
802 #define ast_asprintf(ret, fmt, ...) \
803         __ast_asprintf(__FILE__, __LINE__, __PRETTY_FUNCTION__, (ret), (fmt), __VA_ARGS__)
804
805 /*!
806  * \brief A wrapper for vasprintf()
807  *
808  * ast_vasprintf() is a wrapper for vasprintf() that will generate an Asterisk log
809  * message in the case that the allocation fails.
810  *
811  * The arguments and return value are the same as vasprintf()
812  */
813 #define ast_vasprintf(ret, fmt, ap) \
814         __ast_vasprintf((ret), (fmt), (ap), __FILE__, __LINE__, __PRETTY_FUNCTION__)
815
816 /*!
817   \brief call __builtin_alloca to ensure we get gcc builtin semantics
818   \param size The size of the buffer we want allocated
819
820   This macro will attempt to allocate memory from the stack.  If it fails
821   you won't get a NULL returned, but a SEGFAULT if you're lucky.
822 */
823 #define ast_alloca(size) __builtin_alloca(size)
824
825 #if !defined(ast_strdupa) && defined(__GNUC__)
826 /*!
827  * \brief duplicate a string in memory from the stack
828  * \param s The string to duplicate
829  *
830  * This macro will duplicate the given string.  It returns a pointer to the stack
831  * allocatted memory for the new string.
832  */
833 #define ast_strdupa(s)                                                    \
834         (__extension__                                                    \
835         ({                                                                \
836                 const char *__old = (s);                                  \
837                 size_t __len = strlen(__old) + 1;                         \
838                 char *__new = __builtin_alloca(__len);                    \
839                 memcpy (__new, __old, __len);                             \
840                 __new;                                                    \
841         }))
842 #endif
843
844 /*!
845  * \brief Disable PMTU discovery on a socket
846  * \param sock The socket to manipulate
847  * \return Nothing
848  *
849  * On Linux, UDP sockets default to sending packets with the Dont Fragment (DF)
850  * bit set. This is supposedly done to allow the application to do PMTU
851  * discovery, but Asterisk does not do this.
852  *
853  * Because of this, UDP packets sent by Asterisk that are larger than the MTU
854  * of any hop in the path will be lost. This function can be called on a socket
855  * to ensure that the DF bit will not be set.
856  */
857 void ast_enable_packet_fragmentation(int sock);
858
859 /*!
860  * \brief Recursively create directory path
861  * \param path The directory path to create
862  * \param mode The permissions with which to try to create the directory
863  * \return 0 on success or an error code otherwise
864  *
865  * Creates a directory path, creating parent directories as needed.
866  */
867 int ast_mkdir(const char *path, int mode);
868
869 /*!
870  * \brief Recursively create directory path, but only if it resolves within
871  * the given \a base_path.
872  *
873  * If \a base_path does not exist, it will not be created and this function
874  * returns \c EPERM.
875  *
876  * \param path The directory path to create
877  * \param mode The permissions with which to try to create the directory
878  * \return 0 on success or an error code otherwise
879  */
880 int ast_safe_mkdir(const char *base_path, const char *path, int mode);
881
882 #define ARRAY_LEN(a) (size_t) (sizeof(a) / sizeof(0[a]))
883
884 /*!
885  * \brief Checks to see if value is within the given bounds
886  *
887  * \param v the value to check
888  * \param min minimum lower bound (inclusive)
889  * \param max maximum upper bound (inclusive)
890  * \return 0 if value out of bounds, otherwise true (non-zero)
891  */
892 #define IN_BOUNDS(v, min, max) ((v) >= (min)) && ((v) <= (max))
893
894 /*!
895  * \brief Checks to see if value is within the bounds of the given array
896  *
897  * \param v the value to check
898  * \param a the array to bound check
899  * \return 0 if value out of bounds, otherwise true (non-zero)
900  */
901 #define ARRAY_IN_BOUNDS(v, a) IN_BOUNDS((int) (v), 0, ARRAY_LEN(a) - 1)
902
903 /* Definition for Digest authorization */
904 struct ast_http_digest {
905         AST_DECLARE_STRING_FIELDS(
906                 AST_STRING_FIELD(username);
907                 AST_STRING_FIELD(nonce);
908                 AST_STRING_FIELD(uri);
909                 AST_STRING_FIELD(realm);
910                 AST_STRING_FIELD(domain);
911                 AST_STRING_FIELD(response);
912                 AST_STRING_FIELD(cnonce);
913                 AST_STRING_FIELD(opaque);
914                 AST_STRING_FIELD(nc);
915         );
916         int qop;                /* Flag set to 1, if we send/recv qop="quth" */
917 };
918
919 /*!
920  * \brief Parse digest authorization header.
921  * \return Returns -1 if we have no auth or something wrong with digest.
922  * \note This function may be used for Digest request and responce header.
923  * request arg is set to nonzero, if we parse Digest Request.
924  * pedantic arg can be set to nonzero if we need to do addition Digest check.
925  */
926 int ast_parse_digest(const char *digest, struct ast_http_digest *d, int request, int pedantic);
927
928 #ifdef DO_CRASH
929 #define DO_CRASH_NORETURN attribute_noreturn
930 #else
931 #define DO_CRASH_NORETURN
932 #endif
933
934 void DO_CRASH_NORETURN __ast_assert_failed(int condition, const char *condition_str,
935         const char *file, int line, const char *function);
936
937 #ifdef AST_DEVMODE
938 #define ast_assert(a) _ast_assert(a, # a, __FILE__, __LINE__, __PRETTY_FUNCTION__)
939 static void force_inline _ast_assert(int condition, const char *condition_str, const char *file, int line, const char *function)
940 {
941         if (__builtin_expect(!condition, 1)) {
942                 __ast_assert_failed(condition, condition_str, file, line, function);
943         }
944 }
945 #else
946 #define ast_assert(a)
947 #endif
948
949 /*!
950  * \brief Force a crash if DO_CRASH is defined.
951  *
952  * \note If DO_CRASH is not defined then the function returns.
953  *
954  * \return Nothing
955  */
956 void DO_CRASH_NORETURN ast_do_crash(void);
957
958 #include "asterisk/strings.h"
959
960 /*!
961  * \brief Return the number of bytes used in the alignment of type.
962  * \param type
963  * \return The number of bytes required for alignment.
964  *
965  * This is really just __alignof__(), but tucked away in this header so we
966  * don't have to look at the nasty underscores in the source.
967  */
968 #define ast_alignof(type) __alignof__(type)
969
970 /*!
971  * \brief Increase offset so it is a multiple of the required alignment of type.
972  * \param offset The value that should be increased.
973  * \param type The data type that offset should be aligned to.
974  * \return The smallest multiple of alignof(type) larger than or equal to offset.
975  * \see ast_make_room_for()
976  *
977  * Many systems prefer integers to be stored on aligned on memory locations.
978  * This macro will increase an offset so a value of the supplied type can be
979  * safely be stored on such a memory location.
980  *
981  * Examples:
982  * ast_align_for(0x17, int64_t) ==> 0x18
983  * ast_align_for(0x18, int64_t) ==> 0x18
984  * ast_align_for(0x19, int64_t) ==> 0x20
985  *
986  * Don't mind the ugliness, the compiler will optimize it.
987  */
988 #define ast_align_for(offset, type) (((offset + __alignof__(type) - 1) / __alignof__(type)) * __alignof__(type))
989
990 /*!
991  * \brief Increase offset by the required alignment of type and make sure it is
992  *        a multiple of said alignment.
993  * \param offset The value that should be increased.
994  * \param type The data type that room should be reserved for.
995  * \return The smallest multiple of alignof(type) larger than or equal to offset
996  *         plus alignof(type).
997  * \see ast_align_for()
998  *
999  * A use case for this is when prepending length fields of type int to a buffer.
1000  * If you keep the offset a multiple of the alignment of the integer type,
1001  * a next block of length+buffer will have the length field automatically
1002  * aligned.
1003  *
1004  * Examples:
1005  * ast_make_room_for(0x17, int64_t) ==> 0x20
1006  * ast_make_room_for(0x18, int64_t) ==> 0x20
1007  * ast_make_room_for(0x19, int64_t) ==> 0x28
1008  *
1009  * Don't mind the ugliness, the compiler will optimize it.
1010  */
1011 #define ast_make_room_for(offset, type) (((offset + (2 * __alignof__(type) - 1)) / __alignof__(type)) * __alignof__(type))
1012
1013 /*!
1014  * \brief An Entity ID is essentially a MAC address, brief and unique
1015  */
1016 struct ast_eid {
1017         unsigned char eid[6];
1018 } __attribute__((__packed__));
1019
1020 /*!
1021  * \brief Global EID
1022  *
1023  * This is set in asterisk.conf, or determined automatically by taking the mac
1024  * address of an Ethernet interface on the system.
1025  */
1026 extern struct ast_eid ast_eid_default;
1027
1028 /*!
1029  * \brief Fill in an ast_eid with the default eid of this machine
1030  * \since 1.6.1
1031  */
1032 void ast_set_default_eid(struct ast_eid *eid);
1033
1034 /*!
1035  * \brief Convert an EID to a string
1036  * \since 1.6.1
1037  */
1038 char *ast_eid_to_str(char *s, int maxlen, struct ast_eid *eid);
1039
1040 /*!
1041  * \brief Convert a string into an EID
1042  *
1043  * This function expects an EID in the format:
1044  *    00:11:22:33:44:55
1045  *
1046  * \return 0 success, non-zero failure
1047  * \since 1.6.1
1048  */
1049 int ast_str_to_eid(struct ast_eid *eid, const char *s);
1050
1051 /*!
1052  * \brief Compare two EIDs
1053  *
1054  * \return 0 if the two are the same, non-zero otherwise
1055  * \since 1.6.1
1056  */
1057 int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2);
1058
1059 /*!
1060  * \brief Check if EID is empty
1061  *
1062  * \return 1 if the EID is empty, zero otherwise
1063  * \since 13.12.0
1064  */
1065 int ast_eid_is_empty(const struct ast_eid *eid);
1066
1067 /*!
1068  * \brief Get current thread ID
1069  * \return the ID if platform is supported, else -1
1070  */
1071 int ast_get_tid(void);
1072
1073 /*!
1074  * \brief Resolve a binary to a full pathname
1075  * \param binary Name of the executable to resolve
1076  * \param fullpath Buffer to hold the complete pathname
1077  * \param fullpath_size Size of \a fullpath
1078  * \retval NULL \a binary was not found or the environment variable PATH is not set
1079  * \return \a fullpath
1080  */
1081 char *ast_utils_which(const char *binary, char *fullpath, size_t fullpath_size);
1082
1083 /*!
1084  * \brief Declare a variable that will call a destructor function when it goes out of scope.
1085  *
1086  * Resource Allocation Is Initialization (RAII) variable declaration.
1087  *
1088  * \since 11.0
1089  * \param vartype The type of the variable
1090  * \param varname The name of the variable
1091  * \param initval The initial value of the variable
1092  * \param dtor The destructor function of type' void func(vartype *)'
1093  *
1094  * \code
1095  * void mything_cleanup(struct mything *t)
1096  * {
1097  *     if (t) {
1098  *         ast_free(t->stuff);
1099  *     }
1100  * }
1101  *
1102  * void do_stuff(const char *name)
1103  * {
1104  *     RAII_VAR(struct mything *, thing, mything_alloc(name), mything_cleanup);
1105  *     ...
1106  * }
1107  * \endcode
1108  *
1109  * \note This macro is especially useful for working with ao2 objects. A common idiom
1110  * would be a function that needed to look up an ao2 object and might have several error
1111  * conditions after the allocation that would normally need to unref the ao2 object.
1112  * With RAII_VAR, it is possible to just return and leave the cleanup to the destructor
1113  * function. For example:
1114  *
1115  * \code
1116  * void do_stuff(const char *name)
1117  * {
1118  *     RAII_VAR(struct mything *, thing, find_mything(name), ao2_cleanup);
1119  *     if (!thing) {
1120  *         return;
1121  *     }
1122  *     if (error) {
1123  *         return;
1124  *     }
1125  *     do_stuff_with_thing(thing);
1126  * }
1127  * \endcode
1128  */
1129
1130 #if defined(__clang__)
1131 typedef void (^_raii_cleanup_block_t)(void);
1132 static inline void _raii_cleanup_block(_raii_cleanup_block_t *b) { (*b)(); }
1133
1134 #define RAII_VAR(vartype, varname, initval, dtor)                                                                \
1135     _raii_cleanup_block_t _raii_cleanup_ ## varname __attribute__((cleanup(_raii_cleanup_block),unused)) = NULL; \
1136     __block vartype varname = initval;                                                                           \
1137     _raii_cleanup_ ## varname = ^{ {(void)dtor(varname);} }
1138
1139 #elif defined(__GNUC__)
1140
1141 #define RAII_VAR(vartype, varname, initval, dtor)                              \
1142     auto void _dtor_ ## varname (vartype * v);                                 \
1143     void _dtor_ ## varname (vartype * v) { dtor(*v); }                         \
1144     vartype varname __attribute__((cleanup(_dtor_ ## varname))) = (initval)
1145
1146 #else
1147     #error "Cannot compile Asterisk: unknown and unsupported compiler."
1148 #endif /* #if __GNUC__ */
1149
1150 /*!
1151  * \brief Asterisk wrapper around crypt(3).
1152  *
1153  * The interpretation of the salt (which determines the password hashing
1154  * algorithm) is system specific. Application code should prefer to use
1155  * ast_crypt_encrypt() or ast_crypt_validate().
1156  *
1157  * The returned string is heap allocated, and should be freed with ast_free().
1158  *
1159  * \param key User's password to crypt.
1160  * \param salt Salt to crypt with.
1161  * \return Crypted password.
1162  * \return \c NULL on error.
1163  */
1164 char *ast_crypt(const char *key, const char *salt);
1165
1166 /*
1167  * \brief Asterisk wrapper around crypt(3) for encrypting passwords.
1168  *
1169  * This function will generate a random salt and encrypt the given password.
1170  *
1171  * The returned string is heap allocated, and should be freed with ast_free().
1172  *
1173  * \param key User's password to crypt.
1174  * \return Crypted password.
1175  * \return \c NULL on error.
1176  */
1177 char *ast_crypt_encrypt(const char *key);
1178
1179 /*
1180  * \brief Asterisk wrapper around crypt(3) for validating passwords.
1181  *
1182  * \param key User's password to validate.
1183  * \param expected Expected result from crypt.
1184  * \return True (non-zero) if \a key matches \a expected.
1185  * \return False (zero) if \a key doesn't match.
1186  */
1187 int ast_crypt_validate(const char *key, const char *expected);
1188
1189 /*
1190  * \brief Test that a file exists and is readable by the effective user.
1191  * \since 13.7.0
1192  *
1193  * \param filename File to test.
1194  * \return True (non-zero) if the file exists and is readable.
1195  * \return False (zero) if the file either doesn't exists or is not readable.
1196  */
1197 int ast_file_is_readable(const char *filename);
1198
1199 /*
1200  * \brief Compare 2 major.minor.patch.extra version strings.
1201  * \since 13.7.0
1202  *
1203  * \param version1.
1204  * \param version2.
1205  *
1206  * \return <0 if version 1 < version 2.
1207  * \return =0 if version 1 = version 2.
1208  * \return >0 if version 1 > version 2.
1209  */
1210 int ast_compare_versions(const char *version1, const char *version2);
1211
1212 /*
1213  * \brief Test that an OS supports IPv6 Networking.
1214  * \since 13.14.0
1215  *
1216  * \return True (non-zero) if the IPv6 supported.
1217  * \return False (zero) if the OS doesn't support IPv6.
1218  */
1219 int ast_check_ipv6(void);
1220
1221 enum ast_fd_flag_operation {
1222         AST_FD_FLAG_SET,
1223         AST_FD_FLAG_CLEAR,
1224 };
1225
1226 /*
1227  * \brief Set flags on the given file descriptor
1228  * \since 13.19
1229  *
1230  * If getting or setting flags of the given file descriptor fails, logs an
1231  * error message.
1232  *
1233  * \param fd File descriptor to set flags on
1234  * \param flags The flag(s) to set
1235  *
1236  * \return -1 on error
1237  * \return 0 if successful
1238  */
1239 #define ast_fd_set_flags(fd, flags) \
1240         __ast_fd_set_flags((fd), (flags), AST_FD_FLAG_SET, __FILE__, __LINE__, __PRETTY_FUNCTION__)
1241
1242 /*
1243  * \brief Clear flags on the given file descriptor
1244  * \since 13.19
1245  *
1246  * If getting or setting flags of the given file descriptor fails, logs an
1247  * error message.
1248  *
1249  * \param fd File descriptor to clear flags on
1250  * \param flags The flag(s) to clear
1251  *
1252  * \return -1 on error
1253  * \return 0 if successful
1254  */
1255 #define ast_fd_clear_flags(fd, flags) \
1256         __ast_fd_set_flags((fd), (flags), AST_FD_FLAG_CLEAR, __FILE__, __LINE__, __PRETTY_FUNCTION__)
1257
1258 int __ast_fd_set_flags(int fd, int flags, enum ast_fd_flag_operation op,
1259         const char *file, int lineno, const char *function);
1260
1261 #endif /* _ASTERISK_UTILS_H */