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