core: Introduce chaos into memory allocations
[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 <execinfo.h>
29 #include <time.h>       /* we want to override localtime_r */
30 #include <unistd.h>
31 #include <string.h>
32
33 #include "asterisk/lock.h"
34 #include "asterisk/time.h"
35 #include "asterisk/logger.h"
36 #include "asterisk/localtime.h"
37 #include "asterisk/stringfields.h"
38
39 /*!
40 \note \verbatim
41    Note:
42    It is very important to use only unsigned variables to hold
43    bit flags, as otherwise you can fall prey to the compiler's
44    sign-extension antics if you try to use the top two bits in
45    your variable.
46
47    The flag macros below use a set of compiler tricks to verify
48    that the caller is using an "unsigned int" variable to hold
49    the flags, and nothing else. If the caller uses any other
50    type of variable, a warning message similar to this:
51
52    warning: comparison of distinct pointer types lacks cast
53    will be generated.
54
55    The "dummy" variable below is used to make these comparisons.
56
57    Also note that at -O2 or above, this type-safety checking
58    does _not_ produce any additional object code at all.
59  \endverbatim
60 */
61
62 extern unsigned int __unsigned_int_flags_dummy;
63
64 #define ast_test_flag(p,flag)           ({ \
65                                         typeof ((p)->flags) __p = (p)->flags; \
66                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
67                                         (void) (&__p == &__x); \
68                                         ((p)->flags & (flag)); \
69                                         })
70
71 #define ast_set_flag(p,flag)            do { \
72                                         typeof ((p)->flags) __p = (p)->flags; \
73                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
74                                         (void) (&__p == &__x); \
75                                         ((p)->flags |= (flag)); \
76                                         } while(0)
77
78 #define ast_clear_flag(p,flag)          do { \
79                                         typeof ((p)->flags) __p = (p)->flags; \
80                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
81                                         (void) (&__p == &__x); \
82                                         ((p)->flags &= ~(flag)); \
83                                         } while(0)
84
85 #define ast_copy_flags(dest,src,flagz)  do { \
86                                         typeof ((dest)->flags) __d = (dest)->flags; \
87                                         typeof ((src)->flags) __s = (src)->flags; \
88                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
89                                         (void) (&__d == &__x); \
90                                         (void) (&__s == &__x); \
91                                         (dest)->flags &= ~(flagz); \
92                                         (dest)->flags |= ((src)->flags & (flagz)); \
93                                         } while (0)
94
95 #define ast_set2_flag(p,value,flag)     do { \
96                                         typeof ((p)->flags) __p = (p)->flags; \
97                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
98                                         (void) (&__p == &__x); \
99                                         if (value) \
100                                                 (p)->flags |= (flag); \
101                                         else \
102                                                 (p)->flags &= ~(flag); \
103                                         } while (0)
104
105 #define ast_set_flags_to(p,flag,value)  do { \
106                                         typeof ((p)->flags) __p = (p)->flags; \
107                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
108                                         (void) (&__p == &__x); \
109                                         (p)->flags &= ~(flag); \
110                                         (p)->flags |= (value); \
111                                         } while (0)
112
113
114 /* The following 64-bit flag code can most likely be erased after app_dial
115    is reorganized to either reduce the large number of options, or handle
116    them in some other way. At the time of this writing, app_dial would be
117    the only user of 64-bit option flags */
118
119 extern uint64_t __unsigned_int_flags_dummy64;
120
121 #define ast_test_flag64(p,flag)                 ({ \
122                                         typeof ((p)->flags) __p = (p)->flags; \
123                                         typeof (__unsigned_int_flags_dummy64) __x = 0; \
124                                         (void) (&__p == &__x); \
125                                         ((p)->flags & (flag)); \
126                                         })
127
128 #define ast_set_flag64(p,flag)          do { \
129                                         typeof ((p)->flags) __p = (p)->flags; \
130                                         typeof (__unsigned_int_flags_dummy64) __x = 0; \
131                                         (void) (&__p == &__x); \
132                                         ((p)->flags |= (flag)); \
133                                         } while(0)
134
135 #define ast_clear_flag64(p,flag)                do { \
136                                         typeof ((p)->flags) __p = (p)->flags; \
137                                         typeof (__unsigned_int_flags_dummy64) __x = 0; \
138                                         (void) (&__p == &__x); \
139                                         ((p)->flags &= ~(flag)); \
140                                         } while(0)
141
142 #define ast_copy_flags64(dest,src,flagz)        do { \
143                                         typeof ((dest)->flags) __d = (dest)->flags; \
144                                         typeof ((src)->flags) __s = (src)->flags; \
145                                         typeof (__unsigned_int_flags_dummy64) __x = 0; \
146                                         (void) (&__d == &__x); \
147                                         (void) (&__s == &__x); \
148                                         (dest)->flags &= ~(flagz); \
149                                         (dest)->flags |= ((src)->flags & (flagz)); \
150                                         } while (0)
151
152 #define ast_set2_flag64(p,value,flag)   do { \
153                                         typeof ((p)->flags) __p = (p)->flags; \
154                                         typeof (__unsigned_int_flags_dummy64) __x = 0; \
155                                         (void) (&__p == &__x); \
156                                         if (value) \
157                                                 (p)->flags |= (flag); \
158                                         else \
159                                                 (p)->flags &= ~(flag); \
160                                         } while (0)
161
162 #define ast_set_flags_to64(p,flag,value)        do { \
163                                         typeof ((p)->flags) __p = (p)->flags; \
164                                         typeof (__unsigned_int_flags_dummy64) __x = 0; \
165                                         (void) (&__p == &__x); \
166                                         (p)->flags &= ~(flag); \
167                                         (p)->flags |= (value); \
168                                         } while (0)
169
170
171 /* Non-type checking variations for non-unsigned int flags.  You
172    should only use non-unsigned int flags where required by
173    protocol etc and if you know what you're doing :)  */
174 #define ast_test_flag_nonstd(p,flag) \
175                                         ((p)->flags & (flag))
176
177 #define ast_set_flag_nonstd(p,flag)             do { \
178                                         ((p)->flags |= (flag)); \
179                                         } while(0)
180
181 #define ast_clear_flag_nonstd(p,flag)           do { \
182                                         ((p)->flags &= ~(flag)); \
183                                         } while(0)
184
185 #define ast_copy_flags_nonstd(dest,src,flagz)   do { \
186                                         (dest)->flags &= ~(flagz); \
187                                         (dest)->flags |= ((src)->flags & (flagz)); \
188                                         } while (0)
189
190 #define ast_set2_flag_nonstd(p,value,flag)      do { \
191                                         if (value) \
192                                                 (p)->flags |= (flag); \
193                                         else \
194                                                 (p)->flags &= ~(flag); \
195                                         } while (0)
196
197 #define AST_FLAGS_ALL UINT_MAX
198
199 /*! \brief Structure used to handle boolean flags */
200 struct ast_flags {
201         unsigned int flags;
202 };
203
204 /*! \brief Structure used to handle a large number of boolean flags == used only in app_dial? */
205 struct ast_flags64 {
206         uint64_t flags;
207 };
208
209 struct ast_hostent {
210         struct hostent hp;
211         char buf[1024];
212 };
213
214 /*! \brief Thread-safe gethostbyname function to use in Asterisk */
215 struct hostent *ast_gethostbyname(const char *host, struct ast_hostent *hp);
216
217 /*! \brief Produces MD5 hash based on input string */
218 void ast_md5_hash(char *output, const char *input);
219 /*! \brief Produces SHA1 hash based on input string */
220 void ast_sha1_hash(char *output, const char *input);
221 /*! \brief Produces SHA1 hash based on input string, stored in uint8_t array */
222 void ast_sha1_hash_uint(uint8_t *digest, const char *input);
223
224 int ast_base64encode_full(char *dst, const unsigned char *src, int srclen, int max, int linebreaks);
225
226 #undef MIN
227 #define MIN(a, b) ({ typeof(a) __a = (a); typeof(b) __b = (b); ((__a > __b) ? __b : __a);})
228 #undef MAX
229 #define MAX(a, b) ({ typeof(a) __a = (a); typeof(b) __b = (b); ((__a < __b) ? __b : __a);})
230
231 #define SWAP(a,b) do { typeof(a) __tmp = (a); (a) = (b); (b) = __tmp; } while (0)
232
233 /*!
234  * \brief Encode data in base64
235  * \param dst the destination buffer
236  * \param src the source data to be encoded
237  * \param srclen the number of bytes present in the source buffer
238  * \param max the maximum number of bytes to write into the destination
239  *        buffer, *including* the terminating NULL character.
240  */
241 int ast_base64encode(char *dst, const unsigned char *src, int srclen, int max);
242
243 /*!
244  * \brief Decode data from base64
245  * \param dst the destination buffer
246  * \param src the source buffer
247  * \param max The maximum number of bytes to write into the destination
248  *            buffer.  Note that this function will not ensure that the
249  *            destination buffer is NULL terminated.  So, in general,
250  *            this parameter should be sizeof(dst) - 1.
251  */
252 int ast_base64decode(unsigned char *dst, const char *src, int max);
253
254 #define AST_URI_ALPHANUM     (1 << 0)
255 #define AST_URI_MARK         (1 << 1)
256 #define AST_URI_UNRESERVED   (AST_URI_ALPHANUM | AST_URI_MARK)
257 #define AST_URI_LEGACY_SPACE (1 << 2)
258
259 #define AST_URI_SIP_USER_UNRESERVED (1 << 20)
260
261 extern const struct ast_flags ast_uri_http;
262 extern const struct ast_flags ast_uri_http_legacy;
263 extern const struct ast_flags ast_uri_sip_user;
264
265 /*!
266  * \brief Turn text string to URI-encoded %XX version
267  *
268  * This function encodes characters according to the rules presented in RFC
269  * 2396 and/or RFC 3261 section 19.1.2 and section 25.1.
270  *
271  * Outbuf needs to have more memory allocated than the instring to have room
272  * for the expansion. Every byte that is converted is replaced by three ASCII
273  * characters.
274  *
275  * \param string string to be converted
276  * \param outbuf resulting encoded string
277  * \param buflen size of output buffer
278  * \param spec flags describing how the encoding should be performed
279  * \return a pointer to the uri encoded string
280  */
281 char *ast_uri_encode(const char *string, char *outbuf, int buflen, struct ast_flags spec);
282
283 /*!
284  * \brief Decode URI, URN, URL (overwrite string)
285  *
286  * \note The ast_uri_http_legacy decode spec flag will cause this function to
287  * decode '+' as ' '.
288  *
289  * \param s string to be decoded
290  * \param spec flags describing how the decoding should be performed
291  */
292 void ast_uri_decode(char *s, struct ast_flags spec);
293
294 /*! ast_xml_escape
295         \brief Escape reserved characters for use in XML.
296
297         If \a outbuf is too short, the output string will be truncated.
298         Regardless, the output will always be null terminated.
299
300         \param string String to be converted
301         \param outbuf Resulting encoded string
302         \param buflen Size of output buffer
303         \return 0 for success
304         \return -1 if buflen is too short.
305  */
306 int ast_xml_escape(const char *string, char *outbuf, size_t buflen);
307
308 /*!
309  * \brief Escape characters found in a quoted string.
310  *
311  * \note This function escapes quoted characters based on the 'qdtext' set of
312  * allowed characters from RFC 3261 section 25.1.
313  *
314  * \param string string to be escaped
315  * \param outbuf resulting escaped string
316  * \param buflen size of output buffer
317  * \return a pointer to the escaped string
318  */
319 char *ast_escape_quoted(const char *string, char *outbuf, int buflen);
320
321 /*!
322  * \brief Escape semicolons found in a string.
323  *
324  * \param string string to be escaped
325  * \param outbuf resulting escaped string
326  * \param buflen size of output buffer
327  * \return a pointer to the escaped string
328  */
329 char *ast_escape_semicolons(const char *string, char *outbuf, int buflen);
330
331 /*!
332  * \brief Unescape quotes in a string
333  *
334  * \param quote_str The string with quotes to be unescaped
335  *
336  * \note This function mutates the passed-in string.
337  */
338 void ast_unescape_quoted(char *quote_str);
339
340 static force_inline void ast_slinear_saturated_add(short *input, short *value)
341 {
342         int res;
343
344         res = (int) *input + *value;
345         if (res > 32767)
346                 *input = 32767;
347         else if (res < -32768)
348                 *input = -32768;
349         else
350                 *input = (short) res;
351 }
352
353 static force_inline void ast_slinear_saturated_subtract(short *input, short *value)
354 {
355         int res;
356
357         res = (int) *input - *value;
358         if (res > 32767)
359                 *input = 32767;
360         else if (res < -32768)
361                 *input = -32768;
362         else
363                 *input = (short) res;
364 }
365
366 static force_inline void ast_slinear_saturated_multiply(short *input, short *value)
367 {
368         int res;
369
370         res = (int) *input * *value;
371         if (res > 32767)
372                 *input = 32767;
373         else if (res < -32768)
374                 *input = -32768;
375         else
376                 *input = (short) res;
377 }
378
379 static force_inline void ast_slinear_saturated_divide(short *input, short *value)
380 {
381         *input /= *value;
382 }
383
384 #ifdef localtime_r
385 #undef localtime_r
386 #endif
387 #define localtime_r __dont_use_localtime_r_use_ast_localtime_instead__
388
389 int ast_utils_init(void);
390 int ast_wait_for_input(int fd, int ms);
391 int ast_wait_for_output(int fd, int ms);
392
393 /*!
394  * \brief Try to write string, but wait no more than ms milliseconds
395  * before timing out.
396  *
397  * \note If you are calling ast_carefulwrite, it is assumed that you are calling
398  * it on a file descriptor that _DOES_ have NONBLOCK set.  This way,
399  * there is only one system call made to do a write, unless we actually
400  * have a need to wait.  This way, we get better performance.
401  */
402 int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
403
404 /*!
405  * \brief Write data to a file stream with a timeout
406  *
407  * \param f the file stream to write to
408  * \param fd the file description to poll on to know when the file stream can
409  *        be written to without blocking.
410  * \param s the buffer to write from
411  * \param len the number of bytes to write
412  * \param timeoutms The maximum amount of time to block in this function trying
413  *        to write, specified in milliseconds.
414  *
415  * \note This function assumes that the associated file stream has been set up
416  *       as non-blocking.
417  *
418  * \retval 0 success
419  * \retval -1 error
420  */
421 int ast_careful_fwrite(FILE *f, int fd, const char *s, size_t len, int timeoutms);
422
423 /*
424  * Thread management support (should be moved to lock.h or a different header)
425  */
426
427 #define AST_STACKSIZE (((sizeof(void *) * 8 * 8) - 16) * 1024)
428
429 #if defined(LOW_MEMORY)
430 #define AST_BACKGROUND_STACKSIZE (((sizeof(void *) * 8 * 2) - 16) * 1024)
431 #else
432 #define AST_BACKGROUND_STACKSIZE AST_STACKSIZE
433 #endif
434
435 void ast_register_thread(char *name);
436 void ast_unregister_thread(void *id);
437
438 int ast_pthread_create_stack(pthread_t *thread, pthread_attr_t *attr, void *(*start_routine)(void *),
439                              void *data, size_t stacksize, const char *file, const char *caller,
440                              int line, const char *start_fn);
441
442 int ast_pthread_create_detached_stack(pthread_t *thread, pthread_attr_t *attr, void*(*start_routine)(void *),
443                                  void *data, size_t stacksize, const char *file, const char *caller,
444                                  int line, const char *start_fn);
445
446 #define ast_pthread_create(a, b, c, d)                          \
447         ast_pthread_create_stack(a, b, c, d,                    \
448                 0, __FILE__, __FUNCTION__, __LINE__, #c)
449
450 #define ast_pthread_create_detached(a, b, c, d)                 \
451         ast_pthread_create_detached_stack(a, b, c, d,           \
452                 0, __FILE__, __FUNCTION__, __LINE__, #c)
453
454 #define ast_pthread_create_background(a, b, c, d)               \
455         ast_pthread_create_stack(a, b, c, d,                    \
456                 AST_BACKGROUND_STACKSIZE,                       \
457                 __FILE__, __FUNCTION__, __LINE__, #c)
458
459 #define ast_pthread_create_detached_background(a, b, c, d)      \
460         ast_pthread_create_detached_stack(a, b, c, d,           \
461                 AST_BACKGROUND_STACKSIZE,                       \
462                 __FILE__, __FUNCTION__, __LINE__, #c)
463
464 /* End of thread management support */
465
466 /*!
467  * \brief Replace '^' in a string with ','
468  * \param s String within which to replace characters
469  */
470 void ast_replace_subargument_delimiter(char *s);
471
472 /*!
473  * \brief Process a string to find and replace characters
474  * \param start The string to analyze
475  * \param find The character to find
476  * \param replace_with The character that will replace the one we are looking for
477  */
478 char *ast_process_quotes_and_slashes(char *start, char find, char replace_with);
479
480 long int ast_random(void);
481
482 /*!
483  * \brief Returns a random number between 0.0 and 1.0, inclusive.
484  * \since 12
485  */
486 #define ast_random_double() (((double)ast_random()) / RAND_MAX)
487
488 /*!
489  * \brief DEBUG_CHAOS returns failure randomly
490  *
491  * DEBUG_CHAOS_RETURN(failure); can be used to fake
492  * failure of functions such as memory allocation,
493  * for the purposes of testing failure handling.
494  */
495 #ifdef DEBUG_CHAOS
496 #ifndef DEBUG_CHAOS_ALLOC_CHANCE
497 #define DEBUG_CHAOS_ALLOC_CHANCE 100000
498 #endif
499 /* Could #define DEBUG_CHAOS_ENABLE ast_fully_booted */
500 #ifndef DEBUG_CHAOS_ENABLE
501 #define DEBUG_CHAOS_ENABLE 1
502 #endif
503 #define DEBUG_CHAOS_RETURN(CHANCE, FAILURE) \
504         do { \
505                 if ((DEBUG_CHAOS_ENABLE) && (ast_random() % CHANCE == 0)) { \
506                         return FAILURE; \
507                 } \
508         } while (0)
509 #else
510 #define DEBUG_CHAOS_RETURN(c,f)
511 #endif
512
513
514 #ifndef __AST_DEBUG_MALLOC
515 #define ast_std_malloc malloc
516 #define ast_std_calloc calloc
517 #define ast_std_realloc realloc
518 #define ast_std_free free
519
520 /*!
521  * \brief free() wrapper
522  *
523  * ast_free_ptr should be used when a function pointer for free() needs to be passed
524  * as the argument to a function. Otherwise, astmm will cause seg faults.
525  */
526 #define ast_free free
527 #define ast_free_ptr ast_free
528
529 /*
530  * This buffer is in static memory. We never intend to read it,
531  * nor do we care about multiple threads writing to it at the
532  * same time. We only want to know if we're recursing too deep
533  * already. 60 entries should be more than enough.  Function
534  * call depth rarely exceeds 20 or so.
535  */
536 #define _AST_MEM_BACKTRACE_BUFLEN 60
537 extern void *_ast_mem_backtrace_buffer[_AST_MEM_BACKTRACE_BUFLEN];
538
539 /*
540  * Ok, this sucks. But if we're already out of mem, we don't
541  * want the logger to create infinite recursion (and a crash).
542  */
543 #define MALLOC_FAILURE_MSG \
544         do { \
545                 if (backtrace(_ast_mem_backtrace_buffer, _AST_MEM_BACKTRACE_BUFLEN) < _AST_MEM_BACKTRACE_BUFLEN) { \
546                         ast_log(LOG_ERROR, "Memory Allocation Failure in function %s at line %d of %s\n", func, lineno, file); \
547                 } \
548         } while (0)
549
550 /*!
551  * \brief A wrapper for malloc()
552  *
553  * ast_malloc() is a wrapper for malloc() that will generate an Asterisk log
554  * message in the case that the allocation fails.
555  *
556  * The argument and return value are the same as malloc()
557  */
558 #define ast_malloc(len) \
559         _ast_malloc((len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
560
561 AST_INLINE_API(
562 void * attribute_malloc _ast_malloc(size_t len, const char *file, int lineno, const char *func),
563 {
564         void *p;
565
566         DEBUG_CHAOS_RETURN(DEBUG_CHAOS_ALLOC_CHANCE, NULL);
567
568         if (!(p = malloc(len))) {
569                 MALLOC_FAILURE_MSG;
570         }
571
572         return p;
573 }
574 )
575
576 /*!
577  * \brief A wrapper for calloc()
578  *
579  * ast_calloc() is a wrapper for calloc() that will generate an Asterisk log
580  * message in the case that the allocation fails.
581  *
582  * The arguments and return value are the same as calloc()
583  */
584 #define ast_calloc(num, len) \
585         _ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
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         if (!(p = calloc(num, len))) {
595                 MALLOC_FAILURE_MSG;
596         }
597
598         return p;
599 }
600 )
601
602 /*!
603  * \brief A wrapper for calloc() for use in cache pools
604  *
605  * ast_calloc_cache() is a wrapper for calloc() that will generate an Asterisk log
606  * message in the case that the allocation fails. When memory debugging is in use,
607  * the memory allocated by this function will be marked as 'cache' so it can be
608  * distinguished from normal memory allocations.
609  *
610  * The arguments and return value are the same as calloc()
611  */
612 #define ast_calloc_cache(num, len) \
613         _ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
614
615 /*!
616  * \brief A wrapper for realloc()
617  *
618  * ast_realloc() is a wrapper for realloc() that will generate an Asterisk log
619  * message in the case that the allocation fails.
620  *
621  * The arguments and return value are the same as realloc()
622  */
623 #define ast_realloc(p, len) \
624         _ast_realloc((p), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
625
626 AST_INLINE_API(
627 void * attribute_malloc _ast_realloc(void *p, size_t len, const char *file, int lineno, const char *func),
628 {
629         void *newp;
630
631         DEBUG_CHAOS_RETURN(DEBUG_CHAOS_ALLOC_CHANCE, NULL);
632
633         if (!(newp = realloc(p, len))) {
634                 MALLOC_FAILURE_MSG;
635         }
636
637         return newp;
638 }
639 )
640
641 /*!
642  * \brief A wrapper for strdup()
643  *
644  * ast_strdup() is a wrapper for strdup() that will generate an Asterisk log
645  * message in the case that the allocation fails.
646  *
647  * ast_strdup(), unlike strdup(), can safely accept a NULL argument. If a NULL
648  * argument is provided, ast_strdup will return NULL without generating any
649  * kind of error log message.
650  *
651  * The argument and return value are the same as strdup()
652  */
653 #define ast_strdup(str) \
654         _ast_strdup((str), __FILE__, __LINE__, __PRETTY_FUNCTION__)
655
656 AST_INLINE_API(
657 char * attribute_malloc _ast_strdup(const char *str, const char *file, int lineno, const char *func),
658 {
659         char *newstr = NULL;
660
661         DEBUG_CHAOS_RETURN(DEBUG_CHAOS_ALLOC_CHANCE, NULL);
662
663         if (str) {
664                 if (!(newstr = strdup(str))) {
665                         MALLOC_FAILURE_MSG;
666                 }
667         }
668
669         return newstr;
670 }
671 )
672
673 /*!
674  * \brief A wrapper for strndup()
675  *
676  * ast_strndup() is a wrapper for strndup() that will generate an Asterisk log
677  * message in the case that the allocation fails.
678  *
679  * ast_strndup(), unlike strndup(), can safely accept a NULL argument for the
680  * string to duplicate. If a NULL argument is provided, ast_strdup will return
681  * NULL without generating any kind of error log message.
682  *
683  * The arguments and return value are the same as strndup()
684  */
685 #define ast_strndup(str, len) \
686         _ast_strndup((str), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
687
688 AST_INLINE_API(
689 char * attribute_malloc _ast_strndup(const char *str, size_t len, const char *file, int lineno, const char *func),
690 {
691         char *newstr = NULL;
692
693         DEBUG_CHAOS_RETURN(DEBUG_CHAOS_ALLOC_CHANCE, NULL);
694
695         if (str) {
696                 if (!(newstr = strndup(str, len))) {
697                         MALLOC_FAILURE_MSG;
698                 }
699         }
700
701         return newstr;
702 }
703 )
704
705 /*!
706  * \brief A wrapper for asprintf()
707  *
708  * ast_asprintf() is a wrapper for asprintf() that will generate an Asterisk log
709  * message in the case that the allocation fails.
710  *
711  * The arguments and return value are the same as asprintf()
712  */
713 #define ast_asprintf(ret, fmt, ...) \
714         _ast_asprintf((ret), __FILE__, __LINE__, __PRETTY_FUNCTION__, fmt, __VA_ARGS__)
715
716 int __attribute__((format(printf, 5, 6)))
717         _ast_asprintf(char **ret, const char *file, int lineno, const char *func, const char *fmt, ...);
718
719 /*!
720  * \brief A wrapper for vasprintf()
721  *
722  * ast_vasprintf() is a wrapper for vasprintf() that will generate an Asterisk log
723  * message in the case that the allocation fails.
724  *
725  * The arguments and return value are the same as vasprintf()
726  */
727 #define ast_vasprintf(ret, fmt, ap) \
728         _ast_vasprintf((ret), __FILE__, __LINE__, __PRETTY_FUNCTION__, (fmt), (ap))
729
730 AST_INLINE_API(
731 __attribute__((format(printf, 5, 0)))
732 int _ast_vasprintf(char **ret, const char *file, int lineno, const char *func, const char *fmt, va_list ap),
733 {
734         int res;
735
736         DEBUG_CHAOS_RETURN(DEBUG_CHAOS_ALLOC_CHANCE, -1);
737
738         if ((res = vasprintf(ret, fmt, ap)) == -1) {
739                 MALLOC_FAILURE_MSG;
740         }
741
742         return res;
743 }
744 )
745
746 #endif /* AST_DEBUG_MALLOC */
747
748 /*!
749   \brief call __builtin_alloca to ensure we get gcc builtin semantics
750   \param size The size of the buffer we want allocated
751
752   This macro will attempt to allocate memory from the stack.  If it fails
753   you won't get a NULL returned, but a SEGFAULT if you're lucky.
754 */
755 #define ast_alloca(size) __builtin_alloca(size)
756
757 #if !defined(ast_strdupa) && defined(__GNUC__)
758 /*!
759  * \brief duplicate a string in memory from the stack
760  * \param s The string to duplicate
761  *
762  * This macro will duplicate the given string.  It returns a pointer to the stack
763  * allocatted memory for the new string.
764  */
765 #define ast_strdupa(s)                                                    \
766         (__extension__                                                    \
767         ({                                                                \
768                 const char *__old = (s);                                  \
769                 size_t __len = strlen(__old) + 1;                         \
770                 char *__new = __builtin_alloca(__len);                    \
771                 memcpy (__new, __old, __len);                             \
772                 __new;                                                    \
773         }))
774 #endif
775
776 /*!
777  * \brief Disable PMTU discovery on a socket
778  * \param sock The socket to manipulate
779  * \return Nothing
780  *
781  * On Linux, UDP sockets default to sending packets with the Dont Fragment (DF)
782  * bit set. This is supposedly done to allow the application to do PMTU
783  * discovery, but Asterisk does not do this.
784  *
785  * Because of this, UDP packets sent by Asterisk that are larger than the MTU
786  * of any hop in the path will be lost. This function can be called on a socket
787  * to ensure that the DF bit will not be set.
788  */
789 void ast_enable_packet_fragmentation(int sock);
790
791 /*!
792  * \brief Recursively create directory path
793  * \param path The directory path to create
794  * \param mode The permissions with which to try to create the directory
795  * \return 0 on success or an error code otherwise
796  *
797  * Creates a directory path, creating parent directories as needed.
798  */
799 int ast_mkdir(const char *path, int mode);
800
801 /*!
802  * \brief Recursively create directory path, but only if it resolves within
803  * the given \a base_path.
804  *
805  * If \a base_path does not exist, it will not be created and this function
806  * returns \c EPERM.
807  *
808  * \param path The directory path to create
809  * \param mode The permissions with which to try to create the directory
810  * \return 0 on success or an error code otherwise
811  */
812 int ast_safe_mkdir(const char *base_path, const char *path, int mode);
813
814 #define ARRAY_LEN(a) (size_t) (sizeof(a) / sizeof(0[a]))
815
816 /*!
817  * \brief Checks to see if value is within the given bounds
818  *
819  * \param v the value to check
820  * \param min minimum lower bound (inclusive)
821  * \param max maximum upper bound (inclusive)
822  * \return 0 if value out of bounds, otherwise true (non-zero)
823  */
824 #define IN_BOUNDS(v, min, max) ((v) >= (min)) && ((v) <= (max))
825
826 /*!
827  * \brief Checks to see if value is within the bounds of the given array
828  *
829  * \param v the value to check
830  * \param a the array to bound check
831  * \return 0 if value out of bounds, otherwise true (non-zero)
832  */
833 #define ARRAY_IN_BOUNDS(v, a) IN_BOUNDS(v, 0, ARRAY_LEN(a) - 1)
834
835 /* Definition for Digest authorization */
836 struct ast_http_digest {
837         AST_DECLARE_STRING_FIELDS(
838                 AST_STRING_FIELD(username);
839                 AST_STRING_FIELD(nonce);
840                 AST_STRING_FIELD(uri);
841                 AST_STRING_FIELD(realm);
842                 AST_STRING_FIELD(domain);
843                 AST_STRING_FIELD(response);
844                 AST_STRING_FIELD(cnonce);
845                 AST_STRING_FIELD(opaque);
846                 AST_STRING_FIELD(nc);
847         );
848         int qop;                /* Flag set to 1, if we send/recv qop="quth" */
849 };
850
851 /*!
852  * \brief Parse digest authorization header.
853  * \return Returns -1 if we have no auth or something wrong with digest.
854  * \note This function may be used for Digest request and responce header.
855  * request arg is set to nonzero, if we parse Digest Request.
856  * pedantic arg can be set to nonzero if we need to do addition Digest check.
857  */
858 int ast_parse_digest(const char *digest, struct ast_http_digest *d, int request, int pedantic);
859
860
861 #ifdef AST_DEVMODE
862 void __ast_assert_failed(int condition, const char *condition_str, const char *file, int line, const char *function);
863 #define ast_assert(a) _ast_assert(a, # a, __FILE__, __LINE__, __PRETTY_FUNCTION__)
864 static void force_inline _ast_assert(int condition, const char *condition_str, const char *file, int line, const char *function)
865 {
866         if (__builtin_expect(!condition, 1)) {
867                 __ast_assert_failed(condition, condition_str, file, line, function);
868         }
869 }
870 #else
871 #define ast_assert(a)
872 #endif
873
874 /*!
875  * \brief Force a crash if DO_CRASH is defined.
876  *
877  * \note If DO_CRASH is not defined then the function returns.
878  *
879  * \return Nothing
880  */
881 void ast_do_crash(void);
882
883 #include "asterisk/strings.h"
884
885 /*!
886  * \brief Return the number of bytes used in the alignment of type.
887  * \param type
888  * \return The number of bytes required for alignment.
889  *
890  * This is really just __alignof__(), but tucked away in this header so we
891  * don't have to look at the nasty underscores in the source.
892  */
893 #define ast_alignof(type) __alignof__(type)
894
895 /*!
896  * \brief Increase offset so it is a multiple of the required alignment of type.
897  * \param offset The value that should be increased.
898  * \param type The data type that offset should be aligned to.
899  * \return The smallest multiple of alignof(type) larger than or equal to offset.
900  * \see ast_make_room_for()
901  *
902  * Many systems prefer integers to be stored on aligned on memory locations.
903  * This macro will increase an offset so a value of the supplied type can be
904  * safely be stored on such a memory location.
905  *
906  * Examples:
907  * ast_align_for(0x17, int64_t) ==> 0x18
908  * ast_align_for(0x18, int64_t) ==> 0x18
909  * ast_align_for(0x19, int64_t) ==> 0x20
910  *
911  * Don't mind the ugliness, the compiler will optimize it.
912  */
913 #define ast_align_for(offset, type) (((offset + __alignof__(type) - 1) / __alignof__(type)) * __alignof__(type))
914
915 /*!
916  * \brief Increase offset by the required alignment of type and make sure it is
917  *        a multiple of said alignment.
918  * \param offset The value that should be increased.
919  * \param type The data type that room should be reserved for.
920  * \return The smallest multiple of alignof(type) larger than or equal to offset
921  *         plus alignof(type).
922  * \see ast_align_for()
923  *
924  * A use case for this is when prepending length fields of type int to a buffer.
925  * If you keep the offset a multiple of the alignment of the integer type,
926  * a next block of length+buffer will have the length field automatically
927  * aligned.
928  *
929  * Examples:
930  * ast_make_room_for(0x17, int64_t) ==> 0x20
931  * ast_make_room_for(0x18, int64_t) ==> 0x20
932  * ast_make_room_for(0x19, int64_t) ==> 0x28
933  *
934  * Don't mind the ugliness, the compiler will optimize it.
935  */
936 #define ast_make_room_for(offset, type) (((offset + (2 * __alignof__(type) - 1)) / __alignof__(type)) * __alignof__(type))
937
938 /*!
939  * \brief An Entity ID is essentially a MAC address, brief and unique
940  */
941 struct ast_eid {
942         unsigned char eid[6];
943 } __attribute__((__packed__));
944
945 /*!
946  * \brief Global EID
947  *
948  * This is set in asterisk.conf, or determined automatically by taking the mac
949  * address of an Ethernet interface on the system.
950  */
951 extern struct ast_eid ast_eid_default;
952
953 /*!
954  * \brief Fill in an ast_eid with the default eid of this machine
955  * \since 1.6.1
956  */
957 void ast_set_default_eid(struct ast_eid *eid);
958
959 /*!
960  * \brief Convert an EID to a string
961  * \since 1.6.1
962  */
963 char *ast_eid_to_str(char *s, int maxlen, struct ast_eid *eid);
964
965 /*!
966  * \brief Convert a string into an EID
967  *
968  * This function expects an EID in the format:
969  *    00:11:22:33:44:55
970  *
971  * \return 0 success, non-zero failure
972  * \since 1.6.1
973  */
974 int ast_str_to_eid(struct ast_eid *eid, const char *s);
975
976 /*!
977  * \brief Compare two EIDs
978  *
979  * \return 0 if the two are the same, non-zero otherwise
980  * \since 1.6.1
981  */
982 int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2);
983
984 /*!
985  * \brief Get current thread ID
986  * \return the ID if platform is supported, else -1
987  */
988 int ast_get_tid(void);
989
990 /*!
991  * \brief Resolve a binary to a full pathname
992  * \param binary Name of the executable to resolve
993  * \param fullpath Buffer to hold the complete pathname
994  * \param fullpath_size Size of \a fullpath
995  * \retval NULL \a binary was not found or the environment variable PATH is not set
996  * \return \a fullpath
997  */
998 char *ast_utils_which(const char *binary, char *fullpath, size_t fullpath_size);
999
1000 /*!
1001  * \brief Declare a variable that will call a destructor function when it goes out of scope.
1002  *
1003  * Resource Allocation Is Initialization (RAII) variable declaration.
1004  *
1005  * \since 11.0
1006  * \param vartype The type of the variable
1007  * \param varname The name of the variable
1008  * \param initval The initial value of the variable
1009  * \param dtor The destructor function of type' void func(vartype *)'
1010  *
1011  * \code
1012  * void mything_cleanup(struct mything *t)
1013  * {
1014  *     if (t) {
1015  *         ast_free(t->stuff);
1016  *     }
1017  * }
1018  *
1019  * void do_stuff(const char *name)
1020  * {
1021  *     RAII_VAR(struct mything *, thing, mything_alloc(name), mything_cleanup);
1022  *     ...
1023  * }
1024  * \endcode
1025  *
1026  * \note This macro is especially useful for working with ao2 objects. A common idiom
1027  * would be a function that needed to look up an ao2 object and might have several error
1028  * conditions after the allocation that would normally need to unref the ao2 object.
1029  * With RAII_VAR, it is possible to just return and leave the cleanup to the destructor
1030  * function. For example:
1031  *
1032  * \code
1033  * void do_stuff(const char *name)
1034  * {
1035  *     RAII_VAR(struct mything *, thing, find_mything(name), ao2_cleanup);
1036  *     if (!thing) {
1037  *         return;
1038  *     }
1039  *     if (error) {
1040  *         return;
1041  *     }
1042  *     do_stuff_with_thing(thing);
1043  * }
1044  * \endcode
1045  */
1046
1047 #if defined(__clang__)
1048
1049 #if defined(__has_feature) && __has_feature(blocks)
1050 typedef void (^_raii_cleanup_block_t)(void);
1051 static inline void _raii_cleanup_block(_raii_cleanup_block_t *b) { (*b)(); }
1052
1053 #define RAII_VAR(vartype, varname, initval, dtor)                                                                \
1054     _raii_cleanup_block_t _raii_cleanup_ ## varname __attribute__((cleanup(_raii_cleanup_block),unused)) = NULL; \
1055     vartype varname = initval;                                                                                   \
1056     _raii_cleanup_ ## varname = ^{ dtor(varname); }
1057
1058 #else
1059         #error "CLANG must support the 'blocks' feature to compile Asterisk."
1060 #endif /* #if defined(__has_feature) && __has_feature(blocks) */
1061
1062 #elif defined(__GNUC__)
1063
1064 #define RAII_VAR(vartype, varname, initval, dtor)                              \
1065     auto void _dtor_ ## varname (vartype * v);                                 \
1066     void _dtor_ ## varname (vartype * v) { dtor(*v); }                         \
1067     vartype varname __attribute__((cleanup(_dtor_ ## varname))) = (initval)
1068
1069 #else
1070     #error "Cannot compile Asterisk: unknown and unsupported compiler."
1071 #endif /* #if __GNUC__ */
1072
1073 /*!
1074  * \brief Asterisk wrapper around crypt(3).
1075  *
1076  * The interpretation of the salt (which determines the password hashing
1077  * algorithm) is system specific. Application code should prefer to use
1078  * ast_crypt_encrypt() or ast_crypt_validate().
1079  *
1080  * The returned string is heap allocated, and should be freed with ast_free().
1081  *
1082  * \param key User's password to crypt.
1083  * \param salt Salt to crypt with.
1084  * \return Crypted password.
1085  * \return \c NULL on error.
1086  */
1087 char *ast_crypt(const char *key, const char *salt);
1088
1089 /*
1090  * \brief Asterisk wrapper around crypt(3) for encrypting passwords.
1091  *
1092  * This function will generate a random salt and encrypt the given password.
1093  *
1094  * The returned string is heap allocated, and should be freed with ast_free().
1095  *
1096  * \param key User's password to crypt.
1097  * \return Crypted password.
1098  * \return \c NULL on error.
1099  */
1100 char *ast_crypt_encrypt(const char *key);
1101
1102 /*
1103  * \brief Asterisk wrapper around crypt(3) for validating passwords.
1104  *
1105  * \param key User's password to validate.
1106  * \param expected Expected result from crypt.
1107  * \return True (non-zero) if \a key matches \a expected.
1108  * \return False (zero) if \a key doesn't match.
1109  */
1110 int ast_crypt_validate(const char *key, const char *expected);
1111
1112 #endif /* _ASTERISK_UTILS_H */