Asterisk - The Open Source Telephony Project  GIT-master-a24979a
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 struct ast_flags {
200  unsigned int flags;
201 };
202 
203 /*! \brief Structure used to handle a large number of boolean flags == used only in app_dial? */
204 struct ast_flags64 {
205  uint64_t flags;
206 };
207 
208 struct ast_hostent {
209  struct hostent hp;
210  char buf[1024];
211 };
212 
213 /*! \brief Thread-safe gethostbyname function to use in Asterisk */
214 struct hostent *ast_gethostbyname(const char *host, struct ast_hostent *hp);
215 
216 /*! \brief Produces MD5 hash based on input string */
217 void ast_md5_hash(char *output, const char *input);
218 /*! \brief Produces SHA1 hash based on input string */
219 void ast_sha1_hash(char *output, const char *input);
220 /*! \brief Produces SHA1 hash based on input string, stored in uint8_t array */
221 void ast_sha1_hash_uint(uint8_t *digest, const char *input);
222 
223 int ast_base64encode_full(char *dst, const unsigned char *src, int srclen, int max, int linebreaks);
224 
225 #undef MIN
226 #define MIN(a, b) ({ typeof(a) __a = (a); typeof(b) __b = (b); ((__a > __b) ? __b : __a);})
227 #undef MAX
228 #define MAX(a, b) ({ typeof(a) __a = (a); typeof(b) __b = (b); ((__a < __b) ? __b : __a);})
229 
230 #define SWAP(a,b) do { typeof(a) __tmp = (a); (a) = (b); (b) = __tmp; } while (0)
231 
232 /*!
233  * \brief Encode data in base64
234  * \param dst the destination buffer
235  * \param src the source data to be encoded
236  * \param srclen the number of bytes present in the source buffer
237  * \param max the maximum number of bytes to write into the destination
238  * buffer, *including* the terminating NULL character.
239  */
240 int ast_base64encode(char *dst, const unsigned char *src, int srclen, int max);
241 
242 /*!
243  * \brief Same as ast_base64encode, but does hte math for you and returns
244  * an encoded string
245  *
246  * \note The returned string will need to be freed later
247  *
248  * \param src The source buffer
249  *
250  * \retval NULL on failure
251  * \return Encoded string on success
252  */
253 char *ast_base64encode_string(const char *src);
254 
255 /*!
256  * \brief Decode data from base64
257  * \param dst the destination buffer
258  * \param src the source buffer
259  * \param max The maximum number of bytes to write into the destination
260  * buffer. Note that this function will not ensure that the
261  * destination buffer is NULL terminated. So, in general,
262  * this parameter should be sizeof(dst) - 1.
263  */
264 int ast_base64decode(unsigned char *dst, const char *src, int max);
265 
266 /*!
267  * \brief Same as ast_base64decode, but does the math for you and returns
268  * a decoded string
269  *
270  * \note The returned string will need to be freed later and IS NULL terminated
271  *
272  * \param src The source buffer
273  *
274  * \retval NULL on failure
275  * \return Decoded string on success
276  */
277 char *ast_base64decode_string(const char *src);
278 
279 /*!
280  * \brief Decode data from base64 URL
281  *
282  * \param dst The destination buffer
283  * \param src The source buffer
284  * \param max The maximum number of bytes to write into the destination
285  * buffer. Note that this function will not ensure that the
286  * destination buffer is NULL terminated. So, in general,
287  * this parameter should be sizeof(dst) - 1
288  */
289 int ast_base64url_decode(unsigned char *dst, const char *src, int max);
290 
291 /*!
292  * \brief Same as ast_base64encode_full but for base64 URL
293  *
294  * \param dst The destination buffer
295  * \param src The source buffer
296  * \param srclen The number of bytes present in the source buffer
297  * \param max The maximum number of bytes to write into the destination
298  * buffer, *including* the terminating NULL character.
299  * \param linebreaks Set to 1 if there should be linebreaks inserted
300  * in the result
301  */
302 int ast_base64url_encode_full(char *dst, const unsigned char *src, int srclen, int max, int linebreaks);
303 
304 /*!
305  * \brief Encode data in base64 URL
306  *
307  * \param dst The destination buffer
308  * \param src The source data to be encoded
309  * \param srclen The number of bytes present in the source buffer
310  * \param max The maximum number of bytes to write into the destination
311  * buffer, including the terminating NULL character
312  */
313 int ast_base64url_encode(char *dst, const unsigned char *src, int srclen, int max);
314 
315 /*!
316  * \brief Decode string from base64 URL
317  *
318  * \note The returned string will need to be freed later
319  *
320  * \param src The source buffer
321  *
322  * \retval NULL on failure
323  * \return Decoded string on success
324  */
325 char *ast_base64url_decode_string(const char *src);
326 
327 /*!
328  * \brief Encode string in base64 URL
329  *
330  * \note The returned string will need to be freed later
331  *
332  * \param src The source data to be encoded
333  *
334  * \retval NULL on failure
335  * \return Encoded string on success
336  */
337 char *ast_base64url_encode_string(const char *src);
338 
339 /*!
340  * \brief Performs a base 64 encode algorithm on the contents of a File
341  * \param inputfile A FILE handle to the input file to be encoded. Must be readable. This handle is not automatically closed.
342  * \param outputfile A FILE handle to the output file to receive the base 64 encoded contents of the input file, identified by filename.
343  * \param endl The line ending to use (e.g. either "\n" or "\r\n")
344  *
345  * \return zero on success, -1 on error.
346  */
347 int ast_base64_encode_file(FILE *inputfile, FILE *outputfile, const char *endl);
348 
349 /*!
350  * \brief Performs a base 64 encode algorithm on the contents of a File
351  * \param filename The path to the file to be encoded. Must be readable, file is opened in read mode.
352  * \param outputfile A FILE handle to the output file to receive the base 64 encoded contents of the input file, identified by filename.
353  * \param endl The line ending to use (e.g. either "\n" or "\r\n")
354  *
355  * \return zero on success, -1 on error.
356  */
357 int ast_base64_encode_file_path(const char *filename, FILE *outputfile, const char *endl);
358 
359 #define AST_URI_ALPHANUM (1 << 0)
360 #define AST_URI_MARK (1 << 1)
361 #define AST_URI_UNRESERVED (AST_URI_ALPHANUM | AST_URI_MARK)
362 #define AST_URI_LEGACY_SPACE (1 << 2)
363 
364 #define AST_URI_SIP_USER_UNRESERVED (1 << 20)
365 
366 extern const struct ast_flags ast_uri_http;
367 extern const struct ast_flags ast_uri_http_legacy;
368 extern const struct ast_flags ast_uri_sip_user;
369 
370 /*!
371  * \brief Turn text string to URI-encoded %XX version
372  *
373  * This function encodes characters according to the rules presented in RFC
374  * 2396 and/or RFC 3261 section 19.1.2 and section 25.1.
375  *
376  * Outbuf needs to have more memory allocated than the instring to have room
377  * for the expansion. Every byte that is converted is replaced by three ASCII
378  * characters.
379  *
380  * \param string string to be converted
381  * \param outbuf resulting encoded string
382  * \param buflen size of output buffer
383  * \param spec flags describing how the encoding should be performed
384  * \return a pointer to the uri encoded string
385  */
386 char *ast_uri_encode(const char *string, char *outbuf, int buflen, struct ast_flags spec);
387 
388 /*!
389  * \brief Decode URI, URN, URL (overwrite string)
390  *
391  * \note The ast_uri_http_legacy decode spec flag will cause this function to
392  * decode '+' as ' '.
393  *
394  * \param s string to be decoded
395  * \param spec flags describing how the decoding should be performed
396  */
397 void ast_uri_decode(char *s, struct ast_flags spec);
398 
399 /*! ast_xml_escape
400  \brief Escape reserved characters for use in XML.
401 
402  If \a outbuf is too short, the output string will be truncated.
403  Regardless, the output will always be null terminated.
404 
405  \param string String to be converted
406  \param outbuf Resulting encoded string
407  \param buflen Size of output buffer
408  \retval 0 for success
409  \retval -1 if buflen is too short.
410  */
411 int ast_xml_escape(const char *string, char *outbuf, size_t buflen);
412 
413 /*!
414  * \brief Escape characters found in a quoted string.
415  *
416  * \note This function escapes quoted characters based on the 'qdtext' set of
417  * allowed characters from RFC 3261 section 25.1.
418  *
419  * \param string string to be escaped
420  * \param outbuf resulting escaped string
421  * \param buflen size of output buffer
422  * \return a pointer to the escaped string
423  */
424 char *ast_escape_quoted(const char *string, char *outbuf, int buflen);
425 
426 /*!
427  * \brief Escape semicolons found in a string.
428  *
429  * \param string string to be escaped
430  * \param outbuf resulting escaped string
431  * \param buflen size of output buffer
432  * \return a pointer to the escaped string
433  */
434 char *ast_escape_semicolons(const char *string, char *outbuf, int buflen);
435 
436 /*!
437  * \brief Unescape quotes in a string
438  *
439  * \param quote_str The string with quotes to be unescaped
440  *
441  * \note This function mutates the passed-in string.
442  */
443 void ast_unescape_quoted(char *quote_str);
444 
446 {
447  int res;
448 
449  res = (int) *input + *value;
450  if (res > 32767)
451  *input = 32767;
452  else if (res < -32768)
453  *input = -32768;
454  else
455  *input = (short) res;
456 }
457 
459 {
460  int res;
461 
462  res = (int) *input - *value;
463  if (res > 32767)
464  *input = 32767;
465  else if (res < -32768)
466  *input = -32768;
467  else
468  *input = (short) res;
469 }
470 
472 {
473  int res;
474 
475  res = (int) *input * *value;
476  if (res > 32767)
477  *input = 32767;
478  else if (res < -32768)
479  *input = -32768;
480  else
481  *input = (short) res;
482 }
483 
485 {
486  float res;
487 
488  res = (float) *input * *value;
489  if (res > 32767)
490  *input = 32767;
491  else if (res < -32768)
492  *input = -32768;
493  else
494  *input = (short) res;
495 }
496 
498 {
499  *input /= *value;
500 }
501 
503 {
504  float res = (float) *input / *value;
505  if (res > 32767)
506  *input = 32767;
507  else if (res < -32768)
508  *input = -32768;
509  else
510  *input = (short) res;
511 }
512 
513 #ifdef localtime_r
514 #undef localtime_r
515 #endif
516 #define localtime_r __dont_use_localtime_r_use_ast_localtime_instead__
517 
518 int ast_utils_init(void);
519 int ast_wait_for_input(int fd, int ms);
520 int ast_wait_for_output(int fd, int ms);
521 
522 /*!
523  * \brief Try to write string, but wait no more than ms milliseconds
524  * before timing out.
525  *
526  * \note If you are calling ast_carefulwrite, it is assumed that you are calling
527  * it on a file descriptor that _DOES_ have NONBLOCK set. This way,
528  * there is only one system call made to do a write, unless we actually
529  * have a need to wait. This way, we get better performance.
530  */
531 int ast_carefulwrite(int fd, char *s, int len, int timeoutms);
532 
533 /*!
534  * \brief Write data to a file stream with a timeout
535  *
536  * \param f the file stream to write to
537  * \param fd the file description to poll on to know when the file stream can
538  * be written to without blocking.
539  * \param s the buffer to write from
540  * \param len the number of bytes to write
541  * \param timeoutms The maximum amount of time to block in this function trying
542  * to write, specified in milliseconds.
543  *
544  * \note This function assumes that the associated file stream has been set up
545  * as non-blocking.
546  *
547  * \retval 0 success
548  * \retval -1 error
549  */
550 int ast_careful_fwrite(FILE *f, int fd, const char *s, size_t len, int timeoutms);
551 
552 /*
553  * Thread management support (should be moved to lock.h or a different header)
554  */
555 
556 #if defined(PTHREAD_STACK_MIN)
557 # define AST_STACKSIZE MAX((((sizeof(void *) * 8 * 8) - 16) * 1024), PTHREAD_STACK_MIN)
558 # define AST_STACKSIZE_LOW MAX((((sizeof(void *) * 8 * 2) - 16) * 1024), PTHREAD_STACK_MIN)
559 #else
560 # define AST_STACKSIZE (((sizeof(void *) * 8 * 8) - 16) * 1024)
561 # define AST_STACKSIZE_LOW (((sizeof(void *) * 8 * 2) - 16) * 1024)
562 #endif
563 
564 int ast_background_stacksize(void);
565 
566 #define AST_BACKGROUND_STACKSIZE ast_background_stacksize()
567 
568 void ast_register_thread(char *name);
569 void ast_unregister_thread(void *id);
570 
571 int ast_pthread_create_stack(pthread_t *thread, pthread_attr_t *attr, void *(*start_routine)(void *),
572  void *data, size_t stacksize, const char *file, const char *caller,
573  int line, const char *start_fn);
574 
575 int ast_pthread_create_detached_stack(pthread_t *thread, pthread_attr_t *attr, void*(*start_routine)(void *),
576  void *data, size_t stacksize, const char *file, const char *caller,
577  int line, const char *start_fn);
578 
579 #define ast_pthread_create(a, b, c, d) \
580  ast_pthread_create_stack(a, b, c, d, \
581  0, __FILE__, __FUNCTION__, __LINE__, #c)
582 
583 #define ast_pthread_create_detached(a, b, c, d) \
584  ast_pthread_create_detached_stack(a, b, c, d, \
585  0, __FILE__, __FUNCTION__, __LINE__, #c)
586 
587 #define ast_pthread_create_background(a, b, c, d) \
588  ast_pthread_create_stack(a, b, c, d, \
589  AST_BACKGROUND_STACKSIZE, \
590  __FILE__, __FUNCTION__, __LINE__, #c)
591 
592 #define ast_pthread_create_detached_background(a, b, c, d) \
593  ast_pthread_create_detached_stack(a, b, c, d, \
594  AST_BACKGROUND_STACKSIZE, \
595  __FILE__, __FUNCTION__, __LINE__, #c)
596 
597 /* End of thread management support */
598 
599 /*!
600  * \brief Replace '^' in a string with ','
601  * \param s String within which to replace characters
602  */
604 
605 /*!
606  * \brief Process a string to find and replace characters
607  * \param start The string to analyze
608  * \param find The character to find
609  * \param replace_with The character that will replace the one we are looking for
610  */
611 char *ast_process_quotes_and_slashes(char *start, char find, char replace_with);
612 
613 long int ast_random(void);
614 
615 /*!
616  * \brief Returns a random number between 0.0 and 1.0, inclusive.
617  * \since 12
618  */
619 #define ast_random_double() (((double)ast_random()) / RAND_MAX)
620 
621 /*!
622  * \brief Disable PMTU discovery on a socket
623  * \param sock The socket to manipulate
624  *
625  * On Linux, UDP sockets default to sending packets with the Dont Fragment (DF)
626  * bit set. This is supposedly done to allow the application to do PMTU
627  * discovery, but Asterisk does not do this.
628  *
629  * Because of this, UDP packets sent by Asterisk that are larger than the MTU
630  * of any hop in the path will be lost. This function can be called on a socket
631  * to ensure that the DF bit will not be set.
632  */
633 void ast_enable_packet_fragmentation(int sock);
634 
635 /*!
636  * \brief Recursively create directory path
637  * \param path The directory path to create
638  * \param mode The permissions with which to try to create the directory
639  * \retval 0 on success
640  * \return error code otherwise
641  *
642  * Creates a directory path, creating parent directories as needed.
643  */
644 int ast_mkdir(const char *path, int mode);
645 
646 /*!
647  * \brief Recursively create directory path, but only if it resolves within
648  * the given \a base_path.
649  *
650  * If \a base_path does not exist, it will not be created and this function
651  * returns \c EPERM.
652  *
653  * \param base_path
654  * \param path The directory path to create
655  * \param mode The permissions with which to try to create the directory
656  * \retval 0 on success
657  * \return an error code otherwise
658  */
659 int ast_safe_mkdir(const char *base_path, const char *path, int mode);
660 
661 #define ARRAY_LEN(a) (size_t) (sizeof(a) / sizeof(0[a]))
662 
663 /*!
664  * \brief Checks to see if value is within the given bounds
665  *
666  * \param v the value to check
667  * \param min minimum lower bound (inclusive)
668  * \param max maximum upper bound (inclusive)
669  * \retval 0 if value out of bounds
670  * \retval non-zero otherwise
671  */
672 #define IN_BOUNDS(v, min, max) ((v) >= (min)) && ((v) <= (max))
673 
674 /*!
675  * \brief Checks to see if value is within the bounds of the given array
676  *
677  * \param v the value to check
678  * \param a the array to bound check
679  * \retval 0 if value out of bounds
680  * \retval non-zero otherwise
681  */
682 #define ARRAY_IN_BOUNDS(v, a) IN_BOUNDS((int) (v), 0, ARRAY_LEN(a) - 1)
683 
684 /* Definition for Digest authorization */
696  );
697  int qop; /* Flag set to 1, if we send/recv qop="quth" */
698 };
699 
700 /*!
701  * \brief Parse digest authorization header.
702  * \return -1 if we have no auth or something wrong with digest.
703  * \note This function may be used for Digest request and responce header.
704  * request arg is set to nonzero, if we parse Digest Request.
705  * pedantic arg can be set to nonzero if we need to do addition Digest check.
706  */
707 int ast_parse_digest(const char *digest, struct ast_http_digest *d, int request, int pedantic);
708 
709 #ifdef DO_CRASH
710 #define DO_CRASH_NORETURN attribute_noreturn
711 #else
712 #define DO_CRASH_NORETURN
713 #endif
714 
715 void DO_CRASH_NORETURN __ast_assert_failed(int condition, const char *condition_str,
716  const char *file, int line, const char *function);
717 
718 #ifdef AST_DEVMODE
719 #define ast_assert(a) _ast_assert(a, # a, __FILE__, __LINE__, __PRETTY_FUNCTION__)
720 #define ast_assert_return(a, ...) \
721 ({ \
722  if (__builtin_expect(!(a), 1)) { \
723  _ast_assert(0, # a, __FILE__, __LINE__, __PRETTY_FUNCTION__); \
724  return __VA_ARGS__; \
725  }\
726 })
727 static void force_inline _ast_assert(int condition, const char *condition_str, const char *file, int line, const char *function)
728 {
729  if (__builtin_expect(!condition, 1)) {
730  __ast_assert_failed(condition, condition_str, file, line, function);
731  }
732 }
733 #else
734 #define ast_assert(a)
735 #define ast_assert_return(a, ...) \
736 ({ \
737  if (__builtin_expect(!(a), 1)) { \
738  return __VA_ARGS__; \
739  }\
740 })
741 #endif
742 
743 /*!
744  * \brief Force a crash if DO_CRASH is defined.
745  *
746  * \note If DO_CRASH is not defined then the function returns.
747  */
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  * \retval 0 success
839  * \retval non-zero failure
840  * \since 1.6.1
841  */
842 int ast_str_to_eid(struct ast_eid *eid, const char *s);
843 
844 /*!
845  * \brief Compare two EIDs
846  *
847  * \retval 0 if the two are the same
848  * \retval non-zero otherwise
849  * \since 1.6.1
850  */
851 int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2);
852 
853 /*!
854  * \brief Check if EID is empty
855  *
856  * \retval 1 if the EID is empty
857  * \retval 0 otherwise
858  * \since 13.12.0
859  */
860 int ast_eid_is_empty(const struct ast_eid *eid);
861 
862 /*!
863  * \brief Get current thread ID
864  * \return the ID if platform is supported, else -1
865  */
866 int ast_get_tid(void);
867 
868 /*!
869  * \brief Resolve a binary to a full pathname
870  * \param binary Name of the executable to resolve
871  * \param fullpath Buffer to hold the complete pathname
872  * \param fullpath_size Size of \a fullpath
873  * \retval NULL \a binary was not found or the environment variable PATH is not set
874  * \return \a fullpath
875  */
876 char *ast_utils_which(const char *binary, char *fullpath, size_t fullpath_size);
877 
878 /*!
879  * \brief Declare a variable that will call a destructor function when it goes out of scope.
880  *
881  * Resource Allocation Is Initialization (RAII) variable declaration.
882  *
883  * \since 11.0
884  * \param vartype The type of the variable
885  * \param varname The name of the variable
886  * \param initval The initial value of the variable
887  * \param dtor The destructor function of type' void func(vartype *)'
888  *
889  * \code
890  * void mything_cleanup(struct mything *t)
891  * {
892  * if (t) {
893  * ast_free(t->stuff);
894  * }
895  * }
896  *
897  * void do_stuff(const char *name)
898  * {
899  * RAII_VAR(struct mything *, thing, mything_alloc(name), mything_cleanup);
900  * ...
901  * }
902  * \endcode
903  *
904  * \note This macro is especially useful for working with ao2 objects. A common idiom
905  * would be a function that needed to look up an ao2 object and might have several error
906  * conditions after the allocation that would normally need to unref the ao2 object.
907  * With RAII_VAR, it is possible to just return and leave the cleanup to the destructor
908  * function. For example:
909  *
910  * \code
911  * void do_stuff(const char *name)
912  * {
913  * RAII_VAR(struct mything *, thing, find_mything(name), ao2_cleanup);
914  * if (!thing) {
915  * return;
916  * }
917  * if (error) {
918  * return;
919  * }
920  * do_stuff_with_thing(thing);
921  * }
922  * \endcode
923  */
924 
925 #if defined(__clang__)
926 typedef void (^_raii_cleanup_block_t)(void);
927 static inline void _raii_cleanup_block(_raii_cleanup_block_t *b) { (*b)(); }
928 
929 #define RAII_VAR(vartype, varname, initval, dtor) \
930  __block vartype varname = initval; \
931  _raii_cleanup_block_t _raii_cleanup_ ## varname __attribute__((cleanup(_raii_cleanup_block),unused)) = \
932  ^{ {(void)dtor(varname);} };
933 
934 #elif defined(__GNUC__)
935 
936 #define RAII_VAR(vartype, varname, initval, dtor) \
937  auto void _dtor_ ## varname (vartype * v); \
938  void _dtor_ ## varname (vartype * v) { dtor(*v); } \
939  vartype varname __attribute__((cleanup(_dtor_ ## varname))) = (initval)
940 
941 #else
942  #error "Cannot compile Asterisk: unknown and unsupported compiler."
943 #endif /* #if __GNUC__ */
944 
945 /*!
946  * \brief Asterisk wrapper around crypt(3).
947  *
948  * The interpretation of the salt (which determines the password hashing
949  * algorithm) is system specific. Application code should prefer to use
950  * ast_crypt_encrypt() or ast_crypt_validate().
951  *
952  * The returned string is heap allocated, and should be freed with ast_free().
953  *
954  * \param key User's password to crypt.
955  * \param salt Salt to crypt with.
956  * \return Crypted password.
957  * \retval NULL on error.
958  */
959 char *ast_crypt(const char *key, const char *salt);
960 
961 /*!
962  * \brief Asterisk wrapper around crypt(3) for encrypting passwords.
963  *
964  * This function will generate a random salt and encrypt the given password.
965  *
966  * The returned string is heap allocated, and should be freed with ast_free().
967  *
968  * \param key User's password to crypt.
969  * \return Crypted password.
970  * \retval NULL on error.
971  */
972 char *ast_crypt_encrypt(const char *key);
973 
974 /*!
975  * \brief Asterisk wrapper around crypt(3) for validating passwords.
976  *
977  * \param key User's password to validate.
978  * \param expected Expected result from crypt.
979  * \retval True (non-zero) if \a key matches \a expected.
980  * \retval False (zero) if \a key doesn't match.
981  */
982 int ast_crypt_validate(const char *key, const char *expected);
983 
984 /*!
985  * \brief Test that a file exists and is readable by the effective user.
986  * \since 13.7.0
987  *
988  * \param filename File to test.
989  * \retval True (non-zero) if the file exists and is readable.
990  * \retval False (zero) if the file either doesn't exists or is not readable.
991  */
992 int ast_file_is_readable(const char *filename);
993 
994 /*!
995  * \brief Compare 2 major.minor.patch.extra version strings.
996  * \since 13.7.0
997  *
998  * \param version1
999  * \param version2
1000  *
1001  * \retval negative if version 1 < version 2.
1002  * \retval 0 if version 1 = version 2.
1003  * \retval positive if version 1 > version 2.
1004  */
1005 int ast_compare_versions(const char *version1, const char *version2);
1006 
1007 /*!
1008  * \brief Test that an OS supports IPv6 Networking.
1009  * \since 13.14.0
1010  *
1011  * \retval True (non-zero) if the IPv6 supported.
1012  * \retval False (zero) if the OS doesn't support IPv6.
1013  */
1014 int ast_check_ipv6(void);
1015 
1019 };
1020 
1021 /*!
1022  * \brief Set flags on the given file descriptor
1023  * \since 13.19
1024  *
1025  * If getting or setting flags of the given file descriptor fails, logs an
1026  * error message.
1027  *
1028  * \param fd File descriptor to set flags on
1029  * \param flags The flag(s) to set
1030  *
1031  * \retval -1 on error
1032  * \retval 0 if successful
1033  */
1034 #define ast_fd_set_flags(fd, flags) \
1035  __ast_fd_set_flags((fd), (flags), AST_FD_FLAG_SET, __FILE__, __LINE__, __PRETTY_FUNCTION__)
1036 
1037 /*!
1038  * \brief Clear flags on the given file descriptor
1039  * \since 13.19
1040  *
1041  * If getting or setting flags of the given file descriptor fails, logs an
1042  * error message.
1043  *
1044  * \param fd File descriptor to clear flags on
1045  * \param flags The flag(s) to clear
1046  *
1047  * \retval -1 on error
1048  * \retval 0 if successful
1049  */
1050 #define ast_fd_clear_flags(fd, flags) \
1051  __ast_fd_set_flags((fd), (flags), AST_FD_FLAG_CLEAR, __FILE__, __LINE__, __PRETTY_FUNCTION__)
1052 
1053 int __ast_fd_set_flags(int fd, int flags, enum ast_fd_flag_operation op,
1054  const char *file, int lineno, const char *function);
1055 
1056 /*!
1057  * \brief Create a non-blocking socket
1058  * \since 13.25
1059  *
1060  * Wrapper around socket(2) that sets the O_NONBLOCK flag on the resulting
1061  * socket.
1062  *
1063  * \details
1064  * For parameter and return information, see the man page for
1065  * socket(2).
1066  */
1067 #ifdef HAVE_SOCK_NONBLOCK
1068 # define ast_socket_nonblock(domain, type, protocol) socket((domain), (type) | SOCK_NONBLOCK, (protocol))
1069 #else
1070 int ast_socket_nonblock(int domain, int type, int protocol);
1071 #endif
1072 
1073 /*!
1074  * \brief Create a non-blocking pipe
1075  * \since 13.25
1076  *
1077  * Wrapper around pipe(2) that sets the O_NONBLOCK flag on the resulting
1078  * file descriptors.
1079  *
1080  * \details
1081  * For parameter and return information, see the man page for
1082  * pipe(2).
1083  */
1084 #ifdef HAVE_PIPE2
1085 # define ast_pipe_nonblock(filedes) pipe2((filedes), O_NONBLOCK)
1086 #else
1087 int ast_pipe_nonblock(int filedes[2]);
1088 #endif
1089 
1090 /*!
1091  * \brief Set the current thread's user interface status.
1092  *
1093  * \param is_user_interface Non-zero to mark the thread as a user interface.
1094  *
1095  * \retval True (non-zero) if marking current thread failed.
1096  * \retval False (zero) if successfuly marked current thread.
1097  */
1098 int ast_thread_user_interface_set(int is_user_interface);
1099 
1100 /*!
1101  * \brief Indicates whether the current thread is a user interface
1102  *
1103  * \retval True (non-zero) if thread is a user interface.
1104  * \retval False (zero) if thread is not a user interface.
1105  */
1107 
1108 #endif /* _ASTERISK_UTILS_H */
pthread_t thread
Definition: app_meetme.c:1091
static int input(yyscan_t yyscanner)
Definition: ast_expr2f.c:1584
static const char type[]
Definition: chan_ooh323.c:109
static int request(void *obj)
Definition: chan_pjsip.c:2580
#define force_inline
Definition: compiler.h:29
#define max(a, b)
Definition: f2c.h:198
static const char name[]
Definition: format_mp3.c:68
static int len(struct ast_channel *chan, const char *cmd, char *data, char *buf, size_t buflen)
Support for logging to various files, console and syslog Configuration in file logger....
Custom localtime functions for multiple timezones.
Asterisk locking-related definitions:
Wrapper for network related headers, masking differences between various operating systems....
#define AST_DECLARE_STRING_FIELDS(field_list)
Declare the fields needed in a structure.
Definition: stringfields.h:341
#define AST_STRING_FIELD(name)
Declare a string field.
Definition: stringfields.h:303
String manipulation functions.
An Entity ID is essentially a MAC address, brief and unique.
Definition: utils.h:808
unsigned char eid[6]
Definition: utils.h:809
Structure used to handle a large number of boolean flags == used only in app_dial?
Definition: utils.h:204
uint64_t flags
Definition: utils.h:205
Structure used to handle boolean flags.
Definition: utils.h:199
unsigned int flags
Definition: utils.h:200
char buf[1024]
Definition: utils.h:210
struct hostent hp
Definition: utils.h:209
const ast_string_field response
Definition: utils.h:696
const ast_string_field uri
Definition: utils.h:696
const ast_string_field opaque
Definition: utils.h:696
const ast_string_field cnonce
Definition: utils.h:696
const ast_string_field nonce
Definition: utils.h:696
const ast_string_field username
Definition: utils.h:696
const ast_string_field realm
Definition: utils.h:696
const ast_string_field nc
Definition: utils.h:696
Domain data structure.
Definition: sip.h:887
int value
Definition: syslog.c:37
static struct test_val b
static struct test_val d
Time-related functions and macros.
int ast_thread_is_user_interface(void)
Indicates whether the current thread is a user interface.
Definition: main/utils.c:3144
char * ast_crypt_encrypt(const char *key)
Asterisk wrapper around crypt(3) for encrypting passwords.
Definition: crypt.c:190
void ast_unescape_quoted(char *quote_str)
Unescape quotes in a string.
Definition: main/utils.c:842
static force_inline void ast_slinear_saturated_divide_float(short *input, float *value)
Definition: utils.h:502
static force_inline void ast_slinear_saturated_subtract(short *input, short *value)
Definition: utils.h:458
int ast_base64url_encode_full(char *dst, const unsigned char *src, int srclen, int max, int linebreaks)
Same as ast_base64encode_full but for base64 URL.
Definition: main/utils.c:471
int ast_base64_encode_file(FILE *inputfile, FILE *outputfile, const char *endl)
Performs a base 64 encode algorithm on the contents of a File.
Definition: main/utils.c:648
int ast_base64decode(unsigned char *dst, const char *src, int max)
Decode data from base64.
Definition: main/utils.c:296
int ast_safe_mkdir(const char *base_path, const char *path, int mode)
Recursively create directory path, but only if it resolves within the given base_path.
Definition: main/utils.c:2482
unsigned int __unsigned_int_flags_dummy
int ast_file_is_readable(const char *filename)
Test that a file exists and is readable by the effective user.
Definition: main/utils.c:3003
char * ast_process_quotes_and_slashes(char *start, char find, char replace_with)
Process a string to find and replace characters.
Definition: main/utils.c:2250
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: main/utils.c:1738
#define DO_CRASH_NORETURN
Definition: utils.h:712
ast_fd_flag_operation
Definition: utils.h:1016
@ AST_FD_FLAG_SET
Definition: utils.h:1017
@ AST_FD_FLAG_CLEAR
Definition: utils.h:1018
int __ast_fd_set_flags(int fd, int flags, enum ast_fd_flag_operation op, const char *file, int lineno, const char *function)
Definition: main/utils.c:3046
int ast_background_stacksize(void)
Definition: main/utils.c:1583
static force_inline void ast_slinear_saturated_multiply_float(short *input, float *value)
Definition: utils.h:484
char * ast_base64url_decode_string(const char *src)
Decode string from base64 URL.
Definition: main/utils.c:450
#define ast_socket_nonblock(domain, type, protocol)
Create a non-blocking socket.
Definition: utils.h:1068
char * ast_escape_quoted(const char *string, char *outbuf, int buflen)
Escape characters found in a quoted string.
Definition: main/utils.c:781
void ast_set_default_eid(struct ast_eid *eid)
Fill in an ast_eid with the default eid of this machine.
Definition: main/utils.c:2897
int ast_thread_user_interface_set(int is_user_interface)
Set the current thread's user interface status.
Definition: main/utils.c:3129
int ast_eid_cmp(const struct ast_eid *eid1, const struct ast_eid *eid2)
Compare two EIDs.
Definition: main/utils.c:2990
int ast_base64encode(char *dst, const unsigned char *src, int srclen, int max)
Encode data in base64.
Definition: main/utils.c:406
static force_inline void ast_slinear_saturated_multiply(short *input, short *value)
Definition: utils.h:471
int ast_wait_for_input(int fd, int ms)
Definition: main/utils.c:1665
int ast_parse_digest(const char *digest, struct ast_http_digest *d, int request, int pedantic)
Parse digest authorization header.
Definition: main/utils.c:2536
char * ast_uri_encode(const char *string, char *outbuf, int buflen, struct ast_flags spec)
Turn text string to URI-encoded XX version.
Definition: main/utils.c:723
int ast_crypt_validate(const char *key, const char *expected)
Asterisk wrapper around crypt(3) for validating passwords.
Definition: crypt.c:136
char * ast_escape_semicolons(const char *string, char *outbuf, int buflen)
Escape semicolons found in a string.
Definition: main/utils.c:811
uint64_t __unsigned_int_flags_dummy64
int ast_get_tid(void)
Get current thread ID.
Definition: main/utils.c:2650
long int ast_random(void)
Definition: main/utils.c:2210
int ast_mkdir(const char *path, int mode)
Recursively create directory path.
Definition: main/utils.c:2377
const struct ast_flags ast_uri_http
Definition: main/utils.c:719
int ast_utils_init(void)
Definition: main/utils.c:2515
int ast_wait_for_output(int fd, int ms)
Definition: main/utils.c:1675
char * ast_crypt(const char *key, const char *salt)
Asterisk wrapper around crypt(3).
Definition: crypt.c:121
static force_inline void ast_slinear_saturated_add(short *input, short *value)
Definition: utils.h:445
void ast_enable_packet_fragmentation(int sock)
Disable PMTU discovery on a socket.
Definition: main/utils.c:2367
int ast_xml_escape(const char *string, char *outbuf, size_t buflen)
Escape reserved characters for use in XML.
Definition: main/utils.c:864
int ast_base64url_decode(unsigned char *dst, const char *src, int max)
Decode data from base64 URL.
Definition: main/utils.c:429
int ast_compare_versions(const char *version1, const char *version2)
Compare 2 major.minor.patch.extra version strings.
Definition: main/utils.c:3020
void ast_register_thread(char *name)
Definition: asterisk.c:414
char * ast_eid_to_str(char *s, int maxlen, struct ast_eid *eid)
Convert an EID to a string.
Definition: main/utils.c:2735
int ast_eid_is_empty(const struct ast_eid *eid)
Check if EID is empty.
Definition: main/utils.c:2995
int ast_base64url_encode(char *dst, const unsigned char *src, int srclen, int max)
Encode data in base64 URL.
Definition: main/utils.c:518
void ast_unregister_thread(void *id)
Definition: asterisk.c:430
void DO_CRASH_NORETURN ast_do_crash(void)
Force a crash if DO_CRASH is defined.
Definition: main/utils.c:2700
#define ast_pipe_nonblock(filedes)
Create a non-blocking pipe.
Definition: utils.h:1085
char * ast_base64url_encode_string(const char *src)
Encode string in base64 URL.
Definition: main/utils.c:523
int ast_base64encode_full(char *dst, const unsigned char *src, int srclen, int max, int linebreaks)
encode text to BASE64 coding
Definition: main/utils.c:355
char * ast_base64encode_string(const char *src)
Same as ast_base64encode, but does hte math for you and returns an encoded string.
Definition: main/utils.c:412
void ast_sha1_hash_uint(uint8_t *digest, const char *input)
Produces SHA1 hash based on input string, stored in uint8_t array.
Definition: main/utils.c:284
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.
int ast_check_ipv6(void)
Test that an OS supports IPv6 Networking.
Definition: main/utils.c:2688
struct hostent * ast_gethostbyname(const char *host, struct ast_hostent *hp)
Thread-safe gethostbyname function to use in Asterisk.
Definition: main/utils.c:199
struct ast_eid ast_eid_default
Global EID.
Definition: options.c:93
int ast_str_to_eid(struct ast_eid *eid, const char *s)
Convert a string into an EID.
Definition: main/utils.c:2973
void ast_uri_decode(char *s, struct ast_flags spec)
Decode URI, URN, URL (overwrite string)
Definition: main/utils.c:762
int ast_base64_encode_file_path(const char *filename, FILE *outputfile, const char *endl)
Performs a base 64 encode algorithm on the contents of a File.
Definition: main/utils.c:702
char * ast_base64decode_string(const char *src)
Same as ast_base64decode, but does the math for you and returns a decoded string.
Definition: main/utils.c:323
void ast_replace_subargument_delimiter(char *s)
Replace '^' in a string with ','.
Definition: main/utils.c:2241
void DO_CRASH_NORETURN __ast_assert_failed(int condition, const char *condition_str, const char *file, int line, const char *function)
Definition: main/utils.c:2712
const struct ast_flags ast_uri_sip_user
Definition: main/utils.c:721
void ast_md5_hash(char *output, const char *input)
Produces MD5 hash based on input string.
Definition: main/utils.c:250
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: main/utils.c:1640
void ast_sha1_hash(char *output, const char *input)
Produces SHA1 hash based on input string.
Definition: main/utils.c:266
static force_inline void ast_slinear_saturated_divide(short *input, short *value)
Definition: utils.h:497
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: main/utils.c:1592
const struct ast_flags ast_uri_http_legacy
Definition: main/utils.c:720
char * ast_utils_which(const char *binary, char *fullpath, size_t fullpath_size)
Resolve a binary to a full pathname.
Definition: main/utils.c:2670