Wed Jan 8 2020 09:49:51

Asterisk developer's documentation


utils.h
Go to the documentation of this file.
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 */
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 */
206 struct ast_flags64 {
207  uint64_t flags;
208 };
209 
210 struct ast_hostent {
211  struct hostent hp;
212  char buf[1024];
213 };
214 
215 /*! \brief Thread-safe gethostbyname function to use in Asterisk */
216 struct hostent *ast_gethostbyname(const char *host, struct ast_hostent *hp);
217 
218 /*! \brief Produces MD5 hash based on input string */
219 void ast_md5_hash(char *output, const char *input);
220 /*! \brief Produces SHA1 hash based on input string */
221 void ast_sha1_hash(char *output, 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 /*!
231  * \brief Encode data in base64
232  * \param dst the destination buffer
233  * \param src the source data to be encoded
234  * \param srclen the number of bytes present in the source buffer
235  * \param max the maximum number of bytes to write into the destination
236  * buffer, *including* the terminating NULL character.
237  */
238 int ast_base64encode(char *dst, const unsigned char *src, int srclen, int max);
239 
240 /*!
241  * \brief Decode data from base64
242  * \param dst the destination buffer
243  * \param src the source buffer
244  * \param max The maximum number of bytes to write into the destination
245  * buffer. Note that this function will not ensure that the
246  * destination buffer is NULL terminated. So, in general,
247  * this parameter should be sizeof(dst) - 1.
248  */
249 int ast_base64decode(unsigned char *dst, const char *src, int max);
250 
251 /*! \brief Turn text string to URI-encoded %XX version
252  *
253  * \note
254  * At this point, this function is encoding agnostic; it does not
255  * check whether it is fed legal UTF-8. We escape control
256  * characters (\x00-\x1F\x7F), '%', and all characters above 0x7F.
257  * If do_special_char == 1 we will convert all characters except alnum
258  * and the mark set.
259  * Outbuf needs to have more memory allocated than the instring
260  * to have room for the expansion. Every char that is converted
261  * is replaced by three ASCII characters.
262  *
263  * \param string String to be converted
264  * \param outbuf Resulting encoded string
265  * \param buflen Size of output buffer
266  * \param do_special_char Convert all non alphanum characters execept
267  * those in the mark set as defined by rfc 3261 section 25.1
268  */
269 char *ast_uri_encode(const char *string, char *outbuf, int buflen, int do_special_char);
270 
271 /*! \brief Decode URI, URN, URL (overwrite string)
272  \param s String to be decoded
273  */
274 void ast_uri_decode(char *s);
275 
276 /*! ast_xml_escape
277  \brief Escape reserved characters for use in XML.
278 
279  If \a outbuf is too short, the output string will be truncated.
280  Regardless, the output will always be null terminated.
281 
282  \param string String to be converted
283  \param outbuf Resulting encoded string
284  \param buflen Size of output buffer
285  \return 0 for success
286  \return -1 if buflen is too short.
287  */
288 int ast_xml_escape(const char *string, char *outbuf, size_t buflen);
289 
290 /*!
291  * \brief Escape characters found in a quoted string.
292  *
293  * \note This function escapes quoted characters based on the 'qdtext' set of
294  * allowed characters from RFC 3261 section 25.1.
295  *
296  * \param string string to be escaped
297  * \param outbuf resulting escaped string
298  * \param buflen size of output buffer
299  * \return a pointer to the escaped string
300  */
301 char *ast_escape_quoted(const char *string, char *outbuf, int buflen);
302 
303 /*!
304  * \brief Unescape quotes in a string
305  *
306  * \param quote_str The string with quotes to be unescaped
307  *
308  * \note This function mutates the passed-in string.
309  */
310 void ast_unescape_quoted(char *quote_str);
311 
313 {
314  int res;
315 
316  res = (int) *input + *value;
317  if (res > 32767)
318  *input = 32767;
319  else if (res < -32768)
320  *input = -32768;
321  else
322  *input = (short) res;
323 }
324 
326 {
327  int res;
328 
329  res = (int) *input - *value;
330  if (res > 32767)
331  *input = 32767;
332  else if (res < -32768)
333  *input = -32768;
334  else
335  *input = (short) res;
336 }
337 
339 {
340  int res;
341 
342  res = (int) *input * *value;
343  if (res > 32767)
344  *input = 32767;
345  else if (res < -32768)
346  *input = -32768;
347  else
348  *input = (short) res;
349 }
350 
352 {
353  *input /= *value;
354 }
355 
356 #ifdef localtime_r
357 #undef localtime_r
358 #endif
359 #define localtime_r __dont_use_localtime_r_use_ast_localtime_instead__
360 
361 int ast_utils_init(void);
362 int ast_wait_for_input(int fd, int ms);
363 int ast_wait_for_output(int fd, int ms);
364 
365 /*!
366  \brief Try to write string, but wait no more than ms milliseconds
367  before timing out.
368 
369  \note If you are calling ast_carefulwrite, it is assumed that you are calling
370  it on a file descriptor that _DOES_ have NONBLOCK set. This way,
371  there is only one system call made to do a write, unless we actually
372  have a need to wait. This way, we get better performance.
373 */
374 int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
375 
376 /*!
377  * \brief Write data to a file stream with a timeout
378  *
379  * \param f the file stream to write to
380  * \param fd the file description to poll on to know when the file stream can
381  * be written to without blocking.
382  * \param s the buffer to write from
383  * \param len the number of bytes to write
384  * \param timeoutms The maximum amount of time to block in this function trying
385  * to write, specified in milliseconds.
386  *
387  * \note This function assumes that the associated file stream has been set up
388  * as non-blocking.
389  *
390  * \retval 0 success
391  * \retval -1 error
392  */
393 int ast_careful_fwrite(FILE *f, int fd, const char *s, size_t len, int timeoutms);
394 
395 /*
396  * Thread management support (should be moved to lock.h or a different header)
397  */
398 
399 #define AST_STACKSIZE (((sizeof(void *) * 8 * 8) - 16) * 1024)
400 
401 #if defined(LOW_MEMORY)
402 #define AST_BACKGROUND_STACKSIZE (((sizeof(void *) * 8 * 2) - 16) * 1024)
403 #else
404 #define AST_BACKGROUND_STACKSIZE AST_STACKSIZE
405 #endif
406 
407 void ast_register_thread(char *name);
408 void ast_unregister_thread(void *id);
409 
410 int ast_pthread_create_stack(pthread_t *thread, pthread_attr_t *attr, void *(*start_routine)(void *),
411  void *data, size_t stacksize, const char *file, const char *caller,
412  int line, const char *start_fn);
413 
414 int ast_pthread_create_detached_stack(pthread_t *thread, pthread_attr_t *attr, void*(*start_routine)(void *),
415  void *data, size_t stacksize, const char *file, const char *caller,
416  int line, const char *start_fn);
417 
418 #define ast_pthread_create(a, b, c, d) \
419  ast_pthread_create_stack(a, b, c, d, \
420  0, __FILE__, __FUNCTION__, __LINE__, #c)
421 
422 #define ast_pthread_create_detached(a, b, c, d) \
423  ast_pthread_create_detached_stack(a, b, c, d, \
424  0, __FILE__, __FUNCTION__, __LINE__, #c)
425 
426 #define ast_pthread_create_background(a, b, c, d) \
427  ast_pthread_create_stack(a, b, c, d, \
428  AST_BACKGROUND_STACKSIZE, \
429  __FILE__, __FUNCTION__, __LINE__, #c)
430 
431 #define ast_pthread_create_detached_background(a, b, c, d) \
432  ast_pthread_create_detached_stack(a, b, c, d, \
433  AST_BACKGROUND_STACKSIZE, \
434  __FILE__, __FUNCTION__, __LINE__, #c)
435 
436 /* End of thread management support */
437 
438 /*!
439  \brief Process a string to find and replace characters
440  \param start The string to analyze
441  \param find The character to find
442  \param replace_with The character that will replace the one we are looking for
443 */
444 char *ast_process_quotes_and_slashes(char *start, char find, char replace_with);
445 
446 long int ast_random(void);
447 
448 
449 #ifndef __AST_DEBUG_MALLOC
450 #define ast_std_malloc malloc
451 #define ast_std_calloc calloc
452 #define ast_std_realloc realloc
453 #define ast_std_free free
454 
455 /*!
456  * \brief free() wrapper
457  *
458  * ast_free_ptr should be used when a function pointer for free() needs to be passed
459  * as the argument to a function. Otherwise, astmm will cause seg faults.
460  */
461 #define ast_free free
462 #define ast_free_ptr ast_free
463 
464 #define MALLOC_FAILURE_MSG \
465  ast_log(LOG_ERROR, "Memory Allocation Failure in function %s at line %d of %s\n", func, lineno, file);
466 /*!
467  * \brief A wrapper for malloc()
468  *
469  * ast_malloc() is a wrapper for malloc() that will generate an Asterisk log
470  * message in the case that the allocation fails.
471  *
472  * The argument and return value are the same as malloc()
473  */
474 #define ast_malloc(len) \
475  _ast_malloc((len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
476 
478 void * attribute_malloc _ast_malloc(size_t len, const char *file, int lineno, const char *func),
479 {
480  void *p;
481 
482  if (!(p = malloc(len)))
484 
485  return p;
486 }
487 )
488 
489 /*!
490  * \brief A wrapper for calloc()
491  *
492  * ast_calloc() is a wrapper for calloc() that will generate an Asterisk log
493  * message in the case that the allocation fails.
494  *
495  * The arguments and return value are the same as calloc()
496  */
497 #define ast_calloc(num, len) \
498  _ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
499 
501 void * attribute_malloc _ast_calloc(size_t num, size_t len, const char *file, int lineno, const char *func),
502 {
503  void *p;
504 
505  if (!(p = calloc(num, len)))
507 
508  return p;
509 }
510 )
511 
512 /*!
513  * \brief A wrapper for calloc() for use in cache pools
514  *
515  * ast_calloc_cache() is a wrapper for calloc() that will generate an Asterisk log
516  * message in the case that the allocation fails. When memory debugging is in use,
517  * the memory allocated by this function will be marked as 'cache' so it can be
518  * distinguished from normal memory allocations.
519  *
520  * The arguments and return value are the same as calloc()
521  */
522 #define ast_calloc_cache(num, len) \
523  _ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
524 
525 /*!
526  * \brief A wrapper for realloc()
527  *
528  * ast_realloc() is a wrapper for realloc() that will generate an Asterisk log
529  * message in the case that the allocation fails.
530  *
531  * The arguments and return value are the same as realloc()
532  */
533 #define ast_realloc(p, len) \
534  _ast_realloc((p), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
535 
537 void * attribute_malloc _ast_realloc(void *p, size_t len, const char *file, int lineno, const char *func),
538 {
539  void *newp;
540 
541  if (!(newp = realloc(p, len)))
543 
544  return newp;
545 }
546 )
547 
548 /*!
549  * \brief A wrapper for strdup()
550  *
551  * ast_strdup() is a wrapper for strdup() that will generate an Asterisk log
552  * message in the case that the allocation fails.
553  *
554  * ast_strdup(), unlike strdup(), can safely accept a NULL argument. If a NULL
555  * argument is provided, ast_strdup will return NULL without generating any
556  * kind of error log message.
557  *
558  * The argument and return value are the same as strdup()
559  */
560 #define ast_strdup(str) \
561  _ast_strdup((str), __FILE__, __LINE__, __PRETTY_FUNCTION__)
562 
564 char * attribute_malloc _ast_strdup(const char *str, const char *file, int lineno, const char *func),
565 {
566  char *newstr = NULL;
567 
568  if (str) {
569  if (!(newstr = strdup(str)))
571  }
572 
573  return newstr;
574 }
575 )
576 
577 /*!
578  * \brief A wrapper for strndup()
579  *
580  * ast_strndup() is a wrapper for strndup() that will generate an Asterisk log
581  * message in the case that the allocation fails.
582  *
583  * ast_strndup(), unlike strndup(), can safely accept a NULL argument for the
584  * string to duplicate. If a NULL argument is provided, ast_strdup will return
585  * NULL without generating any kind of error log message.
586  *
587  * The arguments and return value are the same as strndup()
588  */
589 #define ast_strndup(str, len) \
590  _ast_strndup((str), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
591 
593 char * attribute_malloc _ast_strndup(const char *str, size_t len, const char *file, int lineno, const char *func),
594 {
595  char *newstr = NULL;
596 
597  if (str) {
598  if (!(newstr = strndup(str, len)))
600  }
601 
602  return newstr;
603 }
604 )
605 
606 /*!
607  * \brief A wrapper for asprintf()
608  *
609  * ast_asprintf() is a wrapper for asprintf() that will generate an Asterisk log
610  * message in the case that the allocation fails.
611  *
612  * The arguments and return value are the same as asprintf()
613  */
614 #define ast_asprintf(ret, fmt, ...) \
615  _ast_asprintf((ret), __FILE__, __LINE__, __PRETTY_FUNCTION__, fmt, __VA_ARGS__)
616 
617 int __attribute__((format(printf, 5, 6)))
618  _ast_asprintf(char **ret, const char *file, int lineno, const char *func, const char *fmt, ...);
619 
620 /*!
621  * \brief A wrapper for vasprintf()
622  *
623  * ast_vasprintf() is a wrapper for vasprintf() that will generate an Asterisk log
624  * message in the case that the allocation fails.
625  *
626  * The arguments and return value are the same as vasprintf()
627  */
628 #define ast_vasprintf(ret, fmt, ap) \
629  _ast_vasprintf((ret), __FILE__, __LINE__, __PRETTY_FUNCTION__, (fmt), (ap))
630 
632 __attribute__((format(printf, 5, 0)))
633 int _ast_vasprintf(char **ret, const char *file, int lineno, const char *func, const char *fmt, va_list ap),
634 {
635  int res;
636 
637  if ((res = vasprintf(ret, fmt, ap)) == -1)
639 
640  return res;
641 }
642 )
643 
644 #endif /* AST_DEBUG_MALLOC */
645 
646 /*!
647  \brief call __builtin_alloca to ensure we get gcc builtin semantics
648  \param size The size of the buffer we want allocated
649 
650  This macro will attempt to allocate memory from the stack. If it fails
651  you won't get a NULL returned, but a SEGFAULT if you're lucky.
652 */
653 #define ast_alloca(size) __builtin_alloca(size)
654 
655 #if !defined(ast_strdupa) && defined(__GNUC__)
656 /*!
657  \brief duplicate a string in memory from the stack
658  \param s The string to duplicate
659 
660  This macro will duplicate the given string. It returns a pointer to stack
661  allocated memory for the new string.
662 */
663 #define ast_strdupa(s) \
664  (__extension__ \
665  ({ \
666  const char *__old = (s); \
667  size_t __len = strlen(__old) + 1; \
668  char *__new = __builtin_alloca(__len); \
669  memcpy (__new, __old, __len); \
670  __new; \
671  }))
672 #endif
673 
674 /*!
675  \brief Disable PMTU discovery on a socket
676  \param sock The socket to manipulate
677  \return Nothing
678 
679  On Linux, UDP sockets default to sending packets with the Dont Fragment (DF)
680  bit set. This is supposedly done to allow the application to do PMTU
681  discovery, but Asterisk does not do this.
682 
683  Because of this, UDP packets sent by Asterisk that are larger than the MTU
684  of any hop in the path will be lost. This function can be called on a socket
685  to ensure that the DF bit will not be set.
686  */
687 void ast_enable_packet_fragmentation(int sock);
688 
689 /*!
690  \brief Recursively create directory path
691  \param path The directory path to create
692  \param mode The permissions with which to try to create the directory
693  \return 0 on success or an error code otherwise
694 
695  Creates a directory path, creating parent directories as needed.
696  */
697 int ast_mkdir(const char *path, int mode);
698 
699 #define ARRAY_LEN(a) (size_t) (sizeof(a) / sizeof(0[a]))
700 
701 
702 /* Definition for Digest authorization */
714  );
715  int qop; /* Flag set to 1, if we send/recv qop="quth" */
716 };
717 
718 /*!
719  *\brief Parse digest authorization header.
720  *\return Returns -1 if we have no auth or something wrong with digest.
721  *\note This function may be used for Digest request and responce header.
722  * request arg is set to nonzero, if we parse Digest Request.
723  * pedantic arg can be set to nonzero if we need to do addition Digest check.
724  */
725 int ast_parse_digest(const char *digest, struct ast_http_digest *d, int request, int pedantic);
726 
727 
728 #ifdef AST_DEVMODE
729 void __ast_assert_failed(int condition, const char *condition_str, const char *file, int line, const char *function);
730 #define ast_assert(a) _ast_assert(a, # a, __FILE__, __LINE__, __PRETTY_FUNCTION__)
731 static void force_inline _ast_assert(int condition, const char *condition_str, const char *file, int line, const char *function)
732 {
733  if (__builtin_expect(!condition, 1)) {
734  __ast_assert_failed(condition, condition_str, file, line, function);
735  }
736 }
737 #else
738 #define ast_assert(a)
739 #endif
740 
741 /*!
742  * \brief Force a crash if DO_CRASH is defined.
743  *
744  * \note If DO_CRASH is not defined then the function returns.
745  *
746  * \return Nothing
747  */
748 void ast_do_crash(void);
749 
750 #include "asterisk/strings.h"
751 
752 /*!
753  * \brief Return the number of bytes used in the alignment of type.
754  * \param type
755  * \return The number of bytes required for alignment.
756  *
757  * This is really just __alignof__(), but tucked away in this header so we
758  * don't have to look at the nasty underscores in the source.
759  */
760 #define ast_alignof(type) __alignof__(type)
761 
762 /*!
763  * \brief Increase offset so it is a multiple of the required alignment of type.
764  * \param offset The value that should be increased.
765  * \param type The data type that offset should be aligned to.
766  * \return The smallest multiple of alignof(type) larger than or equal to offset.
767  * \see ast_make_room_for()
768  *
769  * Many systems prefer integers to be stored on aligned on memory locations.
770  * This macro will increase an offset so a value of the supplied type can be
771  * safely be stored on such a memory location.
772  *
773  * Examples:
774  * ast_align_for(0x17, int64_t) ==> 0x18
775  * ast_align_for(0x18, int64_t) ==> 0x18
776  * ast_align_for(0x19, int64_t) ==> 0x20
777  *
778  * Don't mind the ugliness, the compiler will optimize it.
779  */
780 #define ast_align_for(offset, type) (((offset + __alignof__(type) - 1) / __alignof__(type)) * __alignof__(type))
781 
782 /*!
783  * \brief Increase offset by the required alignment of type and make sure it is
784  * a multiple of said alignment.
785  * \param offset The value that should be increased.
786  * \param type The data type that room should be reserved for.
787  * \return The smallest multiple of alignof(type) larger than or equal to offset
788  * plus alignof(type).
789  * \see ast_align_for()
790  *
791  * A use case for this is when prepending length fields of type int to a buffer.
792  * If you keep the offset a multiple of the alignment of the integer type,
793  * a next block of length+buffer will have the length field automatically
794  * aligned.
795  *
796  * Examples:
797  * ast_make_room_for(0x17, int64_t) ==> 0x20
798  * ast_make_room_for(0x18, int64_t) ==> 0x20
799  * ast_make_room_for(0x19, int64_t) ==> 0x28
800  *
801  * Don't mind the ugliness, the compiler will optimize it.
802  */
803 #define ast_make_room_for(offset, type) (((offset + (2 * __alignof__(type) - 1)) / __alignof__(type)) * __alignof__(type))
804 
805 /*!
806  * \brief An Entity ID is essentially a MAC address, brief and unique
807  */
808 struct ast_eid {
809  unsigned char eid[6];
810 } __attribute__((__packed__));
811 
812 /*!
813  * \brief Global EID
814  *
815  * This is set in asterisk.conf, or determined automatically by taking the mac
816  * address of an Ethernet interface on the system.
817  */
818 extern struct ast_eid ast_eid_default;
819 
820 /*!
821  * \brief Fill in an ast_eid with the default eid of this machine
822  * \since 1.6.1
823  */
824 void ast_set_default_eid(struct ast_eid *eid);
825 
826 /*!
827  * /brief Convert an EID to a string
828  * \since 1.6.1
829  */
830 char *ast_eid_to_str(char *s, int maxlen, struct ast_eid *eid);
831 
832 /*!
833  * \brief Convert a string into an EID
834  *
835  * This function expects an EID in the format:
836  * 00:11:22:33:44:55
837  *
838  * \return 0 success, non-zero failure
839  * \since 1.6.1
840  */
841 int ast_str_to_eid(struct ast_eid *eid, const char *s);
842 
843 /*!
844  * \brief Compare two EIDs
845  *
846  * \return 0 if the two are the same, non-zero otherwise
847  * \since 1.6.1
848  */
849 int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2);
850 
851 /*!
852  * \brief Get current thread ID
853  *
854  * \since 1.8.28.0
855  *
856  * \return the ID if platform is supported, else -1
857  */
858 int ast_get_tid(void);
859 
860 /*!\brief Resolve a binary to a full pathname
861  * \param binary Name of the executable to resolve
862  * \param fullpath Buffer to hold the complete pathname
863  * \param fullpath_size Size of \a fullpath
864  * \retval NULL \a binary was not found or the environment variable PATH is not set
865  * \return \a fullpath
866  */
867 char *ast_utils_which(const char *binary, char *fullpath, size_t fullpath_size);
868 
869 /*!
870  * \brief Declare a variable that will call a destructor function when it goes out of scope.
871  *
872  * Resource Allocation Is Initialization (RAII) variable declaration.
873  *
874  * \since 1.8.24.0
875  * \param vartype The type of the variable
876  * \param varname The name of the variable
877  * \param initval The initial value of the variable
878  * \param dtor The destructor function of type' void func(vartype *)'
879  *
880  * \code
881  * void mything_cleanup(struct mything *t)
882  * {
883  * if (t) {
884  * ast_free(t->stuff);
885  * }
886  * }
887  *
888  * void do_stuff(const char *name)
889  * {
890  * RAII_VAR(struct mything *, thing, mything_alloc(name), mything_cleanup);
891  * ...
892  * }
893  * \endcode
894  *
895  * \note This macro is especially useful for working with ao2 objects. A common idiom
896  * would be a function that needed to look up an ao2 object and might have several error
897  * conditions after the allocation that would normally need to unref the ao2 object.
898  * With RAII_VAR, it is possible to just return and leave the cleanup to the destructor
899  * function. For example:
900  *
901  * \code
902  * void do_stuff(const char *name)
903  * {
904  * RAII_VAR(struct mything *, thing, find_mything(name), ao2_cleanup);
905  * if (!thing) {
906  * return;
907  * }
908  * if (error) {
909  * return;
910  * }
911  * do_stuff_with_thing(thing);
912  * }
913  * \endcode
914  */
915 #define RAII_VAR(vartype, varname, initval, dtor) \
916  /* Prototype needed due to http://gcc.gnu.org/bugzilla/show_bug.cgi?id=36774 */ \
917  auto void _dtor_ ## varname (vartype * v); \
918  void _dtor_ ## varname (vartype * v) { dtor(*v); } \
919  vartype varname __attribute__((cleanup(_dtor_ ## varname))) = (initval)
920 
921 #endif /* _ASTERISK_UTILS_H */
const ast_string_field cnonce
Definition: utils.h:714
int ast_utils_init(void)
Definition: utils.c:2193
#define ast_strndup(str, len)
A wrapper for strndup()
Definition: utils.h:589
int vasprintf(char **strp, const char *fmt, va_list ap)
pthread_t thread
Definition: app_meetme.c:962
void ast_register_thread(char *name)
Definition: asterisk.c:401
void * _ast_calloc(size_t num, size_t len, const char *file, int lineno, const char *func)
Definition: utils.h:510
void ast_enable_packet_fragmentation(int sock)
Disable PMTU discovery on a socket.
Definition: utils.c:2141
Asterisk locking-related definitions:
#define malloc(a)
Definition: astmm.h:88
String manipulation functions.
#define ast_alloca(size)
call __builtin_alloca to ensure we get gcc builtin semantics
Definition: utils.h:653
#define realloc(a, b)
Definition: astmm.h:100
char * ast_eid_to_str(char *s, int maxlen, struct ast_eid *eid)
Definition: netsock.c:222
int ast_careful_fwrite(FILE *f, int fd, const char *s, size_t len, int timeoutms)
Write data to a file stream with a timeout.
Definition: utils.c:1369
Time-related functions and macros.
int ast_carefulwrite(int fd, char *s, int len, int timeoutms)
Try to write string, but wait no more than ms milliseconds before timing out.
Definition: utils.c:1328
#define force_inline
Definition: compiler.h:29
void ast_uri_decode(char *s)
Decode URI, URN, URL (overwrite string)
Definition: utils.c:484
char * ast_utils_which(const char *binary, char *fullpath, size_t fullpath_size)
Resolve a binary to a full pathname.
Definition: utils.c:2364
const ast_string_field opaque
Definition: utils.h:714
unsigned int flags
Definition: utils.h:201
const ast_string_field domain
Definition: utils.h:714
int ast_pthread_create_detached_stack(pthread_t *thread, pthread_attr_t *attr, void *(*start_routine)(void *), void *data, size_t stacksize, const char *file, const char *caller, int line, const char *start_fn)
Definition: utils.c:1230
#define MALLOC_FAILURE_MSG
Definition: utils.h:464
void ast_set_default_eid(struct ast_eid *eid)
Fill in an ast_eid with the default eid of this machine.
Definition: netsock.c:239
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:235
const ast_string_field username
Definition: utils.h:714
char * ast_uri_encode(const char *string, char *outbuf, int buflen, int do_special_char)
Turn text string to URI-encoded XX version.
Definition: utils.c:398
const char * str
Definition: app_jack.c:144
char * ast_process_quotes_and_slashes(char *start, char find, char replace_with)
Process a string to find and replace characters.
Definition: utils.c:1664
#define ast_strdup(str)
A wrapper for strdup()
Definition: utils.h:560
#define ast_calloc_cache(num, len)
A wrapper for calloc() for use in cache pools.
Definition: utils.h:522
int value
Definition: syslog.c:39
static int input(yyscan_t yyscanner)
Definition: ast_expr2f.c:1575
int ast_xml_escape(const char *string, char *outbuf, size_t buflen)
Escape reserved characters for use in XML.
Definition: utils.c:500
Structure used to handle a large number of boolean flags == used only in app_dial?
Definition: utils.h:206
An Entity ID is essentially a MAC address, brief and unique.
Definition: utils.h:808
#define calloc(a, b)
Definition: astmm.h:79
int _ast_vasprintf(char **ret, const char *file, int lineno, const char *func, const char *fmt, va_list ap)
Definition: utils.h:642
int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2)
Compare two EIDs.
Definition: netsock.c:320
String fields in structures.
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: utils.h:497
Custom localtime functions for multiple timezones.
int ast_base64decode(unsigned char *dst, const char *src, int max)
Decode data from base64.
Definition: utils.c:279
const ast_string_field uri
Definition: utils.h:714
void ast_unregister_thread(void *id)
Definition: asterisk.c:416
#define ast_asprintf(ret, fmt,...)
A wrapper for asprintf()
Definition: utils.h:614
const ast_string_field response
Definition: utils.h:714
int ast_get_tid(void)
Get current thread ID.
Definition: utils.c:2346
void ast_unescape_quoted(char *quote_str)
Unescape quotes in a string.
Definition: utils.c:461
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:220
long int ast_random(void)
Definition: utils.c:1640
static force_inline void ast_slinear_saturated_add(short *input, short *value)
Definition: utils.h:312
int ast_str_to_eid(struct ast_eid *eid, const char *s)
Convert a string into an EID.
Definition: netsock.c:305
static force_inline void ast_slinear_saturated_multiply(short *input, short *value)
Definition: utils.h:338
char * _ast_strdup(const char *str, const char *file, int lineno, const char *func)
Definition: utils.h:575
Wrapper for network related headers, masking differences between various operating systems...
void ast_sha1_hash(char *output, const char *input)
Produces SHA1 hash based on input string.
Definition: utils.c:261
uint64_t flags
Definition: utils.h:207
unsigned char eid[6]
Definition: utils.h:809
int ast_base64encode(char *dst, const unsigned char *src, int srclen, int max)
Encode data in base64.
Definition: utils.c:357
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
const ast_string_field nc
Definition: utils.h:714
static const char name[]
char * ast_escape_quoted(const char *string, char *outbuf, int buflen)
Escape characters found in a quoted string.
Definition: utils.c:431
static force_inline void ast_slinear_saturated_divide(short *input, short *value)
Definition: utils.h:351
static struct ast_format f[]
Definition: format_g726.c:181
const ast_string_field realm
Definition: utils.h:714
Structure used to handle boolean flags.
Definition: utils.h:200
Support for logging to various files, console and syslog Configuration in file logger.conf.
char buf[1024]
Definition: utils.h:212
struct ast_eid ast_eid_default
Global EID.
Definition: asterisk.c:192
#define attribute_malloc
Definition: compiler.h:59
void ast_do_crash(void)
Force a crash if DO_CRASH is defined.
Definition: utils.c:2382
char * _ast_strndup(const char *str, size_t len, const char *file, int lineno, const char *func)
Definition: utils.h:604
const ast_string_field nonce
Definition: utils.h:714
struct hostent * ast_gethostbyname(const char *host, struct ast_hostent *hp)
Thread-safe gethostbyname function to use in Asterisk.
Definition: utils.c:195
int ast_wait_for_output(int fd, int ms)
Definition: utils.c:1265
int ast_parse_digest(const char *digest, struct ast_http_digest *d, int request, int pedantic)
Parse digest authorization header.
Definition: utils.c:2216
static force_inline void ast_slinear_saturated_subtract(short *input, short *value)
Definition: utils.h:325
int ast_wait_for_input(int fd, int ms)
Definition: utils.c:1255
void * _ast_malloc(size_t len, const char *file, int lineno, const char *func)
Definition: utils.h:487
int ast_pthread_create_stack(pthread_t *thread, pthread_attr_t *attr, void *(*start_routine)(void *), void *data, size_t stacksize, const char *file, const char *caller, int line, const char *start_fn)
Definition: utils.c:1182
#define strdup(a)
Definition: astmm.h:106
struct hostent hp
Definition: utils.h:211
void ast_md5_hash(char *output, const char *input)
Produces MD5 hash based on input string.
Definition: utils.c:245
static struct hostent * hp
Definition: chan_skinny.c:1048
static snd_pcm_format_t format
Definition: chan_alsa.c:93
char * strndup(const char *, size_t)
int ast_base64encode_full(char *dst, const unsigned char *src, int srclen, int max, int linebreaks)
encode text to BASE64 coding
Definition: utils.c:306
uint64_t __unsigned_int_flags_dummy64
unsigned int __unsigned_int_flags_dummy
int _ast_asprintf(char **ret, const char *file, int lineno, const char *func, const char *fmt,...)
Definition: utils.c:2331
int ast_mkdir(const char *path, int mode)
Recursively create directory path.
Definition: utils.c:2151
#define AST_INLINE_API(hdr, body)
Definition: inline_api.h:49
void * _ast_realloc(void *p, size_t len, const char *file, int lineno, const char *func)
Definition: utils.h:546