779db5ea06fa476428fc7b46d9cd661bc80bca99
[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/compat.h"
27
28 #include <stdlib.h>
29 #include <stdio.h>
30 #include <stdarg.h>
31 #include <netinet/in.h>
32 #include <arpa/inet.h>  /* we want to override inet_ntoa */
33 #include <netdb.h>
34 #include <limits.h>
35 #include <string.h>
36 #include <time.h>       /* we want to override localtime_r */
37
38 #include "asterisk/lock.h"
39 #include "asterisk/time.h"
40 #include "asterisk/logger.h"
41 #include "asterisk/compiler.h"
42 #include "asterisk/localtime.h"
43
44 /*! 
45 \note \verbatim
46    Note:
47    It is very important to use only unsigned variables to hold
48    bit flags, as otherwise you can fall prey to the compiler's
49    sign-extension antics if you try to use the top two bits in
50    your variable.
51
52    The flag macros below use a set of compiler tricks to verify
53    that the caller is using an "unsigned int" variable to hold
54    the flags, and nothing else. If the caller uses any other
55    type of variable, a warning message similar to this:
56
57    warning: comparison of distinct pointer types lacks cast
58    will be generated.
59
60    The "dummy" variable below is used to make these comparisons.
61
62    Also note that at -O2 or above, this type-safety checking
63    does _not_ produce any additional object code at all.
64  \endverbatim
65 */
66
67 extern unsigned int __unsigned_int_flags_dummy;
68
69 #define ast_test_flag(p,flag)           ({ \
70                                         typeof ((p)->flags) __p = (p)->flags; \
71                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
72                                         (void) (&__p == &__x); \
73                                         ((p)->flags & (flag)); \
74                                         })
75
76 #define ast_set_flag(p,flag)            do { \
77                                         typeof ((p)->flags) __p = (p)->flags; \
78                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
79                                         (void) (&__p == &__x); \
80                                         ((p)->flags |= (flag)); \
81                                         } while(0)
82
83 #define ast_clear_flag(p,flag)          do { \
84                                         typeof ((p)->flags) __p = (p)->flags; \
85                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
86                                         (void) (&__p == &__x); \
87                                         ((p)->flags &= ~(flag)); \
88                                         } while(0)
89
90 #define ast_copy_flags(dest,src,flagz)  do { \
91                                         typeof ((dest)->flags) __d = (dest)->flags; \
92                                         typeof ((src)->flags) __s = (src)->flags; \
93                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
94                                         (void) (&__d == &__x); \
95                                         (void) (&__s == &__x); \
96                                         (dest)->flags &= ~(flagz); \
97                                         (dest)->flags |= ((src)->flags & (flagz)); \
98                                         } while (0)
99
100 #define ast_set2_flag(p,value,flag)     do { \
101                                         typeof ((p)->flags) __p = (p)->flags; \
102                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
103                                         (void) (&__p == &__x); \
104                                         if (value) \
105                                                 (p)->flags |= (flag); \
106                                         else \
107                                                 (p)->flags &= ~(flag); \
108                                         } while (0)
109
110 #define ast_set_flags_to(p,flag,value)  do { \
111                                         typeof ((p)->flags) __p = (p)->flags; \
112                                         typeof (__unsigned_int_flags_dummy) __x = 0; \
113                                         (void) (&__p == &__x); \
114                                         (p)->flags &= ~(flag); \
115                                         (p)->flags |= (value); \
116                                         } while (0)
117
118 /* Non-type checking variations for non-unsigned int flags.  You
119    should only use non-unsigned int flags where required by 
120    protocol etc and if you know what you're doing :)  */
121 #define ast_test_flag_nonstd(p,flag) \
122                                         ((p)->flags & (flag))
123
124 #define ast_set_flag_nonstd(p,flag)             do { \
125                                         ((p)->flags |= (flag)); \
126                                         } while(0)
127
128 #define ast_clear_flag_nonstd(p,flag)           do { \
129                                         ((p)->flags &= ~(flag)); \
130                                         } while(0)
131
132 #define ast_copy_flags_nonstd(dest,src,flagz)   do { \
133                                         (dest)->flags &= ~(flagz); \
134                                         (dest)->flags |= ((src)->flags & (flagz)); \
135                                         } while (0)
136
137 #define ast_set2_flag_nonstd(p,value,flag)      do { \
138                                         if (value) \
139                                                 (p)->flags |= (flag); \
140                                         else \
141                                                 (p)->flags &= ~(flag); \
142                                         } while (0)
143
144 #define AST_FLAGS_ALL UINT_MAX
145
146 /*! \brief Structure used to handle boolean flags 
147 */
148 struct ast_flags {
149         unsigned int flags;
150 };
151
152 struct ast_hostent {
153         struct hostent hp;
154         char buf[1024];
155 };
156
157 /*! \brief Thread-safe gethostbyname function to use in Asterisk */
158 struct hostent *ast_gethostbyname(const char *host, struct ast_hostent *hp);
159
160 /*!  \brief Produces MD5 hash based on input string */
161 void ast_md5_hash(char *output, char *input);
162 /*! \brief Produces SHA1 hash based on input string */
163 void ast_sha1_hash(char *output, char *input);
164
165 int ast_base64encode_full(char *dst, const unsigned char *src, int srclen, int max, int linebreaks);
166
167 /*!
168  * \brief Encode data in base64
169  * \param dst the destination buffer
170  * \param src the source data to be encoded
171  * \param srclen the number of bytes present in the source buffer
172  * \param max the maximum number of bytes to write into the destination
173  *        buffer, *including* the terminating NULL character.
174  */
175 int ast_base64encode(char *dst, const unsigned char *src, int srclen, int max);
176
177 /*!
178  * \brief Decode data from base64
179  * \param dst the destination buffer
180  * \param src the source buffer
181  * \param max The maximum number of bytes to write into the destination
182  *            buffer.  Note that this function will not ensure that the
183  *            destination buffer is NULL terminated.  So, in general,
184  *            this parameter should be sizeof(dst) - 1.
185  */
186 int ast_base64decode(unsigned char *dst, const char *src, int max);
187
188 /*!  \brief Turn text string to URI-encoded %XX version 
189
190 \note   At this point, we're converting from ISO-8859-x (8-bit), not UTF8
191         as in the SIP protocol spec 
192         If doreserved == 1 we will convert reserved characters also.
193         RFC 2396, section 2.4
194         outbuf needs to have more memory allocated than the instring
195         to have room for the expansion. Every char that is converted
196         is replaced by three ASCII characters.
197         \param string   String to be converted
198         \param outbuf   Resulting encoded string
199         \param buflen   Size of output buffer
200         \param doreserved       Convert reserved characters
201 */
202
203 char *ast_uri_encode(const char *string, char *outbuf, int buflen, int doreserved);
204
205 /*!     \brief Decode URI, URN, URL (overwrite string)
206         \param s        String to be decoded 
207  */
208 void ast_uri_decode(char *s);
209
210 static force_inline void ast_slinear_saturated_add(short *input, short *value)
211 {
212         int res;
213
214         res = (int) *input + *value;
215         if (res > 32767)
216                 *input = 32767;
217         else if (res < -32767)
218                 *input = -32767;
219         else
220                 *input = (short) res;
221 }
222         
223 static force_inline void ast_slinear_saturated_multiply(short *input, short *value)
224 {
225         int res;
226
227         res = (int) *input * *value;
228         if (res > 32767)
229                 *input = 32767;
230         else if (res < -32767)
231                 *input = -32767;
232         else
233                 *input = (short) res;
234 }
235
236 static force_inline void ast_slinear_saturated_divide(short *input, short *value)
237 {
238         *input /= *value;
239 }
240
241 int test_for_thread_safety(void);
242
243 /*!
244  * \brief thread-safe replacement for inet_ntoa().
245  *
246  * \note It is very important to note that even though this is a thread-safe
247  *       replacement for inet_ntoa(), it is *not* reentrant.  In a single
248  *       thread, the result from a previous call to this function is no longer
249  *       valid once it is called again.  If the result from multiple calls to
250  *       this function need to be kept or used at once, then the result must be
251  *       copied to a local buffer before calling this function again.
252  */
253 const char *ast_inet_ntoa(struct in_addr ia);
254
255 #ifdef inet_ntoa
256 #undef inet_ntoa
257 #endif
258 #define inet_ntoa __dont__use__inet_ntoa__use__ast_inet_ntoa__instead__
259
260 #ifdef localtime_r
261 #undef localtime_r
262 #endif
263 #define localtime_r __dont_use_localtime_r_use_ast_localtime_instead__
264
265 int ast_utils_init(void);
266 int ast_wait_for_input(int fd, int ms);
267
268 /*!
269         \brief Try to write string, but wait no more than ms milliseconds
270         before timing out.
271
272         \note If you are calling ast_carefulwrite, it is assumed that you are calling
273         it on a file descriptor that _DOES_ have NONBLOCK set.  This way,
274         there is only one system call made to do a write, unless we actually
275         have a need to wait.  This way, we get better performance.
276 */
277 int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
278
279 /*! \brief Compares the source address and port of two sockaddr_in */
280 static force_inline int inaddrcmp(const struct sockaddr_in *sin1, const struct sockaddr_in *sin2)
281 {
282         return ((sin1->sin_addr.s_addr != sin2->sin_addr.s_addr) 
283                 || (sin1->sin_port != sin2->sin_port));
284 }
285
286 #define AST_STACKSIZE 240 * 1024
287
288 #if defined(LOW_MEMORY)
289 #define AST_BACKGROUND_STACKSIZE 48 * 1024
290 #else
291 #define AST_BACKGROUND_STACKSIZE 240 * 1024
292 #endif
293
294 void ast_register_thread(char *name);
295 void ast_unregister_thread(void *id);
296
297 int ast_pthread_create_stack(pthread_t *thread, pthread_attr_t *attr, void *(*start_routine)(void *),
298                              void *data, size_t stacksize, const char *file, const char *caller,
299                              int line, const char *start_fn);
300
301 int ast_pthread_create_detached_stack(pthread_t *thread, pthread_attr_t *attr, void*(*start_routine)(void *),
302                                  void *data, size_t stacksize, const char *file, const char *caller,
303                                  int line, const char *start_fn);
304
305 #define ast_pthread_create(a, b, c, d) ast_pthread_create_stack(a, b, c, d,                     \
306                                                                 0,                              \
307                                                                 __FILE__, __FUNCTION__,         \
308                                                                 __LINE__, #c)
309 #define ast_pthread_create_detached(a, b, c, d) ast_pthread_create_detached_stack(a, b, c, d, \
310                                                                         0, \
311                                                                         __FILE__, __FUNCTION__, \
312                                                                         __LINE__, #c)
313
314 #define ast_pthread_create_background(a, b, c, d) ast_pthread_create_stack(a, b, c, d,                  \
315                                                                            AST_BACKGROUND_STACKSIZE,    \
316                                                                            __FILE__, __FUNCTION__,      \
317                                                                            __LINE__, #c)
318
319 #define ast_pthread_create_detached_background(a, b, c, d) ast_pthread_create_detached_stack(a, b, c, d, \
320                                                                         AST_BACKGROUND_STACKSIZE, \
321                                                                         __FILE__, __FUNCTION__, \
322                                                                         __LINE__, #c)
323
324 /*!
325         \brief Process a string to find and replace characters
326         \param start The string to analyze
327         \param find The character to find
328         \param replace_with The character that will replace the one we are looking for
329 */
330 char *ast_process_quotes_and_slashes(char *start, char find, char replace_with);
331
332 #ifdef linux
333 #define ast_random random
334 #else
335 long int ast_random(void);
336 #endif
337
338 /*! 
339  * \brief free() wrapper
340  *
341  * ast_free should be used when a function pointer for free() needs to be passed
342  * as the argument to a function. Otherwise, astmm will cause seg faults.
343  */
344 #ifdef __AST_DEBUG_MALLOC
345 static void ast_free(void *ptr) attribute_unused;
346 static void ast_free(void *ptr)
347 {
348         free(ptr);
349 }
350 #else
351 #define ast_free free
352 #endif
353
354 #ifndef __AST_DEBUG_MALLOC
355
356 #define MALLOC_FAILURE_MSG \
357         ast_log(LOG_ERROR, "Memory Allocation Failure in function %s at line %d of %s\n", func, lineno, file);
358 /*!
359  * \brief A wrapper for malloc()
360  *
361  * ast_malloc() is a wrapper for malloc() that will generate an Asterisk log
362  * message in the case that the allocation fails.
363  *
364  * The argument and return value are the same as malloc()
365  */
366 #define ast_malloc(len) \
367         _ast_malloc((len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
368
369 AST_INLINE_API(
370 void * attribute_malloc _ast_malloc(size_t len, const char *file, int lineno, const char *func),
371 {
372         void *p;
373
374         if (!(p = malloc(len)))
375                 MALLOC_FAILURE_MSG;
376
377         return p;
378 }
379 )
380
381 /*!
382  * \brief A wrapper for calloc()
383  *
384  * ast_calloc() is a wrapper for calloc() that will generate an Asterisk log
385  * message in the case that the allocation fails.
386  *
387  * The arguments and return value are the same as calloc()
388  */
389 #define ast_calloc(num, len) \
390         _ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
391
392 AST_INLINE_API(
393 void * attribute_malloc _ast_calloc(size_t num, size_t len, const char *file, int lineno, const char *func),
394 {
395         void *p;
396
397         if (!(p = calloc(num, len)))
398                 MALLOC_FAILURE_MSG;
399
400         return p;
401 }
402 )
403
404 /*!
405  * \brief A wrapper for calloc() for use in cache pools
406  *
407  * ast_calloc_cache() is a wrapper for calloc() that will generate an Asterisk log
408  * message in the case that the allocation fails. When memory debugging is in use,
409  * the memory allocated by this function will be marked as 'cache' so it can be
410  * distinguished from normal memory allocations.
411  *
412  * The arguments and return value are the same as calloc()
413  */
414 #define ast_calloc_cache(num, len) \
415         _ast_calloc((num), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
416
417 /*!
418  * \brief A wrapper for realloc()
419  *
420  * ast_realloc() is a wrapper for realloc() that will generate an Asterisk log
421  * message in the case that the allocation fails.
422  *
423  * The arguments and return value are the same as realloc()
424  */
425 #define ast_realloc(p, len) \
426         _ast_realloc((p), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
427
428 AST_INLINE_API(
429 void * attribute_malloc _ast_realloc(void *p, size_t len, const char *file, int lineno, const char *func),
430 {
431         void *newp;
432
433         if (!(newp = realloc(p, len)))
434                 MALLOC_FAILURE_MSG;
435
436         return newp;
437 }
438 )
439
440 /*!
441  * \brief A wrapper for strdup()
442  *
443  * ast_strdup() is a wrapper for strdup() that will generate an Asterisk log
444  * message in the case that the allocation fails.
445  *
446  * ast_strdup(), unlike strdup(), can safely accept a NULL argument. If a NULL
447  * argument is provided, ast_strdup will return NULL without generating any
448  * kind of error log message.
449  *
450  * The argument and return value are the same as strdup()
451  */
452 #define ast_strdup(str) \
453         _ast_strdup((str), __FILE__, __LINE__, __PRETTY_FUNCTION__)
454
455 AST_INLINE_API(
456 char * attribute_malloc _ast_strdup(const char *str, const char *file, int lineno, const char *func),
457 {
458         char *newstr = NULL;
459
460         if (str) {
461                 if (!(newstr = strdup(str)))
462                         MALLOC_FAILURE_MSG;
463         }
464
465         return newstr;
466 }
467 )
468
469 /*!
470  * \brief A wrapper for strndup()
471  *
472  * ast_strndup() is a wrapper for strndup() that will generate an Asterisk log
473  * message in the case that the allocation fails.
474  *
475  * ast_strndup(), unlike strndup(), can safely accept a NULL argument for the
476  * string to duplicate. If a NULL argument is provided, ast_strdup will return  
477  * NULL without generating any kind of error log message.
478  *
479  * The arguments and return value are the same as strndup()
480  */
481 #define ast_strndup(str, len) \
482         _ast_strndup((str), (len), __FILE__, __LINE__, __PRETTY_FUNCTION__)
483
484 AST_INLINE_API(
485 char * attribute_malloc _ast_strndup(const char *str, size_t len, const char *file, int lineno, const char *func),
486 {
487         char *newstr = NULL;
488
489         if (str) {
490                 if (!(newstr = strndup(str, len)))
491                         MALLOC_FAILURE_MSG;
492         }
493
494         return newstr;
495 }
496 )
497
498 /*!
499  * \brief A wrapper for asprintf()
500  *
501  * ast_asprintf() is a wrapper for asprintf() that will generate an Asterisk log
502  * message in the case that the allocation fails.
503  *
504  * The arguments and return value are the same as asprintf()
505  */
506 #define ast_asprintf(ret, fmt, ...) \
507         _ast_asprintf((ret), __FILE__, __LINE__, __PRETTY_FUNCTION__, fmt, __VA_ARGS__)
508
509 AST_INLINE_API(
510 int _ast_asprintf(char **ret, const char *file, int lineno, const char *func, const char *fmt, ...),
511 {
512         int res;
513         va_list ap;
514
515         va_start(ap, fmt);
516         if ((res = vasprintf(ret, fmt, ap)) == -1)
517                 MALLOC_FAILURE_MSG;
518         va_end(ap);
519
520         return res;
521 }
522 )
523
524 /*!
525  * \brief A wrapper for vasprintf()
526  *
527  * ast_vasprintf() is a wrapper for vasprintf() that will generate an Asterisk log
528  * message in the case that the allocation fails.
529  *
530  * The arguments and return value are the same as vasprintf()
531  */
532 #define ast_vasprintf(ret, fmt, ap) \
533         _ast_vasprintf((ret), __FILE__, __LINE__, __PRETTY_FUNCTION__, (fmt), (ap))
534
535 AST_INLINE_API(
536 int _ast_vasprintf(char **ret, const char *file, int lineno, const char *func, const char *fmt, va_list ap),
537 {
538         int res;
539
540         if ((res = vasprintf(ret, fmt, ap)) == -1)
541                 MALLOC_FAILURE_MSG;
542
543         return res;
544 }
545 )
546
547 #else
548
549 /* If astmm is in use, let it handle these.  Otherwise, it will report that
550    all allocations are coming from this header file */
551
552 #define ast_malloc(a)           malloc(a)
553 #define ast_calloc(a,b)         calloc(a,b)
554 #define ast_realloc(a,b)        realloc(a,b)
555 #define ast_strdup(a)           strdup(a)
556 #define ast_strndup(a,b)        strndup(a,b)
557 #define ast_asprintf(a,b,c)     asprintf(a,b,c)
558 #define ast_vasprintf(a,b,c)    vasprintf(a,b,c)
559
560 #endif /* AST_DEBUG_MALLOC */
561
562 #if !defined(ast_strdupa) && defined(__GNUC__)
563 /*!
564   \brief duplicate a string in memory from the stack
565   \param s The string to duplicate
566
567   This macro will duplicate the given string.  It returns a pointer to the stack
568   allocatted memory for the new string.
569 */
570 #define ast_strdupa(s)                                                    \
571         (__extension__                                                    \
572         ({                                                                \
573                 const char *__old = (s);                                  \
574                 size_t __len = strlen(__old) + 1;                         \
575                 char *__new = __builtin_alloca(__len);                    \
576                 memcpy (__new, __old, __len);                             \
577                 __new;                                                    \
578         }))
579 #endif
580
581 /*!
582   \brief Disable PMTU discovery on a socket
583   \param sock The socket to manipulate
584   \return Nothing
585
586   On Linux, UDP sockets default to sending packets with the Dont Fragment (DF)
587   bit set. This is supposedly done to allow the application to do PMTU
588   discovery, but Asterisk does not do this.
589
590   Because of this, UDP packets sent by Asterisk that are larger than the MTU
591   of any hop in the path will be lost. This function can be called on a socket
592   to ensure that the DF bit will not be set.
593  */
594 void ast_enable_packet_fragmentation(int sock);
595
596 #define ARRAY_LEN(a) (sizeof(a) / sizeof(a[0]))
597
598 #include "asterisk/strings.h"
599
600 #endif /* _ASTERISK_UTILS_H */