1 /* Copyright (c) 2003-2004, Roger Dingledine
2 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
3 * Copyright (c) 2007-2016, The Tor Project, Inc. */
4 /* See LICENSE for licensing information */
8 * \brief Headers for util.c
18 #include "testsupport.h"
22 /* for the correct alias to struct stat */
37 /* If we're building with dmalloc, we want all of our memory allocation
38 * functions to take an extra file/line pair of arguments. If not, not.
39 * We define DMALLOC_PARAMS to the extra parameters to insert in the
40 * function prototypes, and DMALLOC_ARGS to the extra arguments to add
43 #define DMALLOC_PARAMS , const char *file, const int line
44 #define DMALLOC_ARGS , SHORT_FILE__, __LINE__
46 #define DMALLOC_PARAMS
50 /* Memory management */
51 void *tor_malloc_(size_t size DMALLOC_PARAMS
) ATTR_MALLOC
;
52 void *tor_malloc_zero_(size_t size DMALLOC_PARAMS
) ATTR_MALLOC
;
53 void *tor_calloc_(size_t nmemb
, size_t size DMALLOC_PARAMS
) ATTR_MALLOC
;
54 void *tor_realloc_(void *ptr
, size_t size DMALLOC_PARAMS
);
55 void *tor_reallocarray_(void *ptr
, size_t size1
, size_t size2 DMALLOC_PARAMS
);
56 char *tor_strdup_(const char *s DMALLOC_PARAMS
) ATTR_MALLOC
ATTR_NONNULL((1));
57 char *tor_strndup_(const char *s
, size_t n DMALLOC_PARAMS
)
58 ATTR_MALLOC
ATTR_NONNULL((1));
59 void *tor_memdup_(const void *mem
, size_t len DMALLOC_PARAMS
)
60 ATTR_MALLOC
ATTR_NONNULL((1));
61 void *tor_memdup_nulterm_(const void *mem
, size_t len DMALLOC_PARAMS
)
62 ATTR_MALLOC
ATTR_NONNULL((1));
63 void tor_free_(void *mem
);
64 uint64_t tor_htonll(uint64_t a
);
65 uint64_t tor_ntohll(uint64_t a
);
67 extern int dmalloc_free(const char *file
, const int line
, void *pnt
,
69 #define tor_free(p) STMT_BEGIN \
70 if (PREDICT_LIKELY((p)!=NULL)) { \
71 dmalloc_free(SHORT_FILE__, __LINE__, (p), 0); \
76 /** Release memory allocated by tor_malloc, tor_realloc, tor_strdup, etc.
77 * Unlike the free() function, tor_free() will still work on NULL pointers,
78 * and it sets the pointer value to NULL after freeing it.
80 * This is a macro. If you need a function pointer to release memory from
81 * tor_malloc(), use tor_free_().
83 #define tor_free(p) STMT_BEGIN \
84 if (PREDICT_LIKELY((p)!=NULL)) { \
91 #define tor_malloc(size) tor_malloc_(size DMALLOC_ARGS)
92 #define tor_malloc_zero(size) tor_malloc_zero_(size DMALLOC_ARGS)
93 #define tor_calloc(nmemb,size) tor_calloc_(nmemb, size DMALLOC_ARGS)
94 #define tor_realloc(ptr, size) tor_realloc_(ptr, size DMALLOC_ARGS)
95 #define tor_reallocarray(ptr, sz1, sz2) \
96 tor_reallocarray_((ptr), (sz1), (sz2) DMALLOC_ARGS)
97 #define tor_strdup(s) tor_strdup_(s DMALLOC_ARGS)
98 #define tor_strndup(s, n) tor_strndup_(s, n DMALLOC_ARGS)
99 #define tor_memdup(s, n) tor_memdup_(s, n DMALLOC_ARGS)
100 #define tor_memdup_nulterm(s, n) tor_memdup_nulterm_(s, n DMALLOC_ARGS)
102 /* Aliases for the underlying system malloc/realloc/free. Only use
103 * them to indicate "I really want the underlying system function, I know
104 * what I'm doing." */
105 #define raw_malloc malloc
106 #define raw_realloc realloc
107 #define raw_free free
108 #define raw_strdup strdup
110 void tor_log_mallinfo(int severity
);
112 /** Return the offset of <b>member</b> within the type <b>tp</b>, in bytes */
113 #if defined(__GNUC__) && __GNUC__ > 3
114 #define STRUCT_OFFSET(tp, member) __builtin_offsetof(tp, member)
116 #define STRUCT_OFFSET(tp, member) \
117 ((off_t) (((char*)&((tp*)0)->member)-(char*)0))
120 /** Macro: yield a pointer to the field at position <b>off</b> within the
121 * structure <b>st</b>. Example:
123 * struct a { int foo; int bar; } x;
124 * off_t bar_offset = STRUCT_OFFSET(struct a, bar);
125 * int *bar_p = STRUCT_VAR_P(&x, bar_offset);
129 #define STRUCT_VAR_P(st, off) ((void*) ( ((char*)(st)) + (off) ) )
131 /** Macro: yield a pointer to an enclosing structure given a pointer to
132 * a substructure at offset <b>off</b>. Example:
134 * struct base { ... };
135 * struct subtype { int x; struct base b; } x;
136 * struct base *bp = &x.base;
137 * struct *sp = SUBTYPE_P(bp, struct subtype, b);
140 #define SUBTYPE_P(p, subtype, basemember) \
141 ((void*) ( ((char*)(p)) - STRUCT_OFFSET(subtype, basemember) ))
144 /** Macro: true if two values have the same boolean value. */
145 #define bool_eq(a,b) (!(a)==!(b))
146 /** Macro: true if two values have different boolean values. */
147 #define bool_neq(a,b) (!(a)!=!(b))
150 double tor_mathlog(double d
) ATTR_CONST
;
151 long tor_lround(double d
) ATTR_CONST
;
152 int64_t tor_llround(double d
) ATTR_CONST
;
153 int tor_log2(uint64_t u64
) ATTR_CONST
;
154 uint64_t round_to_power_of_2(uint64_t u64
);
155 unsigned round_to_next_multiple_of(unsigned number
, unsigned divisor
);
156 uint32_t round_uint32_to_next_multiple_of(uint32_t number
, uint32_t divisor
);
157 uint64_t round_uint64_to_next_multiple_of(uint64_t number
, uint64_t divisor
);
158 int64_t sample_laplace_distribution(double mu
, double b
, double p
);
159 int64_t add_laplace_noise(int64_t signal
, double random
, double delta_f
,
161 int n_bits_set_u8(uint8_t v
);
162 int64_t clamp_double_to_int64(double number
);
163 void simplify_fraction64(uint64_t *numer
, uint64_t *denom
);
165 /* Compute the CEIL of <b>a</b> divided by <b>b</b>, for nonnegative <b>a</b>
166 * and positive <b>b</b>. Works on integer types only. Not defined if a+b can
168 #define CEIL_DIV(a,b) (((a)+(b)-1)/(b))
170 /* Return <b>v</b> if it's between <b>min</b> and <b>max</b>. Otherwise
171 * return <b>min</b> if <b>v</b> is smaller than <b>min</b>, or <b>max</b> if
172 * <b>b</b> is larger than <b>max</b>.
174 * Requires that <b>min</b> is no more than <b>max</b>. May evaluate any of
175 * its arguments more than once! */
176 #define CLAMP(min,v,max) \
177 ( ((v) < (min)) ? (min) : \
178 ((v) > (max)) ? (max) : \
181 /* String manipulation */
183 /** Allowable characters in a hexadecimal string. */
184 #define HEX_CHARACTERS "0123456789ABCDEFabcdef"
185 void tor_strlower(char *s
) ATTR_NONNULL((1));
186 void tor_strupper(char *s
) ATTR_NONNULL((1));
187 int tor_strisprint(const char *s
) ATTR_NONNULL((1));
188 int tor_strisnonupper(const char *s
) ATTR_NONNULL((1));
189 int strcmp_opt(const char *s1
, const char *s2
);
190 int strcmpstart(const char *s1
, const char *s2
) ATTR_NONNULL((1,2));
191 int strcmp_len(const char *s1
, const char *s2
, size_t len
) ATTR_NONNULL((1,2));
192 int strcasecmpstart(const char *s1
, const char *s2
) ATTR_NONNULL((1,2));
193 int strcmpend(const char *s1
, const char *s2
) ATTR_NONNULL((1,2));
194 int strcasecmpend(const char *s1
, const char *s2
) ATTR_NONNULL((1,2));
195 int fast_memcmpstart(const void *mem
, size_t memlen
, const char *prefix
);
197 void tor_strstrip(char *s
, const char *strip
) ATTR_NONNULL((1,2));
198 long tor_parse_long(const char *s
, int base
, long min
,
199 long max
, int *ok
, char **next
);
200 unsigned long tor_parse_ulong(const char *s
, int base
, unsigned long min
,
201 unsigned long max
, int *ok
, char **next
);
202 double tor_parse_double(const char *s
, double min
, double max
, int *ok
,
204 uint64_t tor_parse_uint64(const char *s
, int base
, uint64_t min
,
205 uint64_t max
, int *ok
, char **next
);
206 const char *hex_str(const char *from
, size_t fromlen
) ATTR_NONNULL((1));
207 const char *eat_whitespace(const char *s
);
208 const char *eat_whitespace_eos(const char *s
, const char *eos
);
209 const char *eat_whitespace_no_nl(const char *s
);
210 const char *eat_whitespace_eos_no_nl(const char *s
, const char *eos
);
211 const char *find_whitespace(const char *s
);
212 const char *find_whitespace_eos(const char *s
, const char *eos
);
213 const char *find_str_at_start_of_line(const char *haystack
,
215 int string_is_C_identifier(const char *string
);
216 int string_is_key_value(int severity
, const char *string
);
217 int string_is_valid_hostname(const char *string
);
218 int string_is_valid_ipv4_address(const char *string
);
219 int string_is_valid_ipv6_address(const char *string
);
221 int tor_mem_is_zero(const char *mem
, size_t len
);
222 int tor_digest_is_zero(const char *digest
);
223 int tor_digest256_is_zero(const char *digest
);
224 char *esc_for_log(const char *string
) ATTR_MALLOC
;
225 char *esc_for_log_len(const char *chars
, size_t n
) ATTR_MALLOC
;
226 const char *escaped(const char *string
);
228 char *tor_escape_str_for_pt_args(const char *string
,
229 const char *chars_to_escape
);
232 int tor_vsscanf(const char *buf
, const char *pattern
, va_list ap
) \
234 int tor_sscanf(const char *buf
, const char *pattern
, ...)
237 void smartlist_add_asprintf(struct smartlist_t
*sl
, const char *pattern
, ...)
239 void smartlist_add_vasprintf(struct smartlist_t
*sl
, const char *pattern
,
244 long tv_udiff(const struct timeval
*start
, const struct timeval
*end
);
245 long tv_mdiff(const struct timeval
*start
, const struct timeval
*end
);
246 int64_t tv_to_msec(const struct timeval
*tv
);
247 int tor_timegm(const struct tm
*tm
, time_t *time_out
);
248 #define RFC1123_TIME_LEN 29
249 void format_rfc1123_time(char *buf
, time_t t
);
250 int parse_rfc1123_time(const char *buf
, time_t *t
);
251 #define ISO_TIME_LEN 19
252 #define ISO_TIME_USEC_LEN (ISO_TIME_LEN+7)
253 void format_local_iso_time(char *buf
, time_t t
);
254 void format_iso_time(char *buf
, time_t t
);
255 void format_iso_time_nospace(char *buf
, time_t t
);
256 void format_iso_time_nospace_usec(char *buf
, const struct timeval
*tv
);
257 int parse_iso_time_(const char *cp
, time_t *t
, int strict
);
258 int parse_iso_time(const char *buf
, time_t *t
);
259 int parse_http_time(const char *buf
, struct tm
*tm
);
260 int format_time_interval(char *out
, size_t out_len
, long interval
);
264 #define approx_time() time(NULL)
265 #define update_approx_time(t) STMT_NIL
267 time_t approx_time(void);
268 void update_approx_time(time_t now
);
273 /** A ratelim_t remembers how often an event is occurring, and how often
274 * it's allowed to occur. Typical usage is something like:
277 if (possibly_very_frequent_event()) {
278 const int INTERVAL = 300;
279 static ratelim_t warning_limit = RATELIM_INIT(INTERVAL);
281 if ((m = rate_limit_log(&warning_limit, approx_time()))) {
282 log_warn(LD_GENERAL, "The event occurred!%s", m);
288 As a convenience wrapper for logging, you can replace the above with:
290 if (possibly_very_frequent_event()) {
291 static ratelim_t warning_limit = RATELIM_INIT(300);
292 log_fn_ratelim(&warning_limit, LOG_WARN, LD_GENERAL,
293 "The event occurred!");
297 typedef struct ratelim_t
{
300 int n_calls_since_last_time
;
303 #define RATELIM_INIT(r) { (r), 0, 0 }
304 #define RATELIM_TOOMANY (16*1000*1000)
306 char *rate_limit_log(ratelim_t
*lim
, time_t now
);
309 ssize_t
write_all(tor_socket_t fd
, const char *buf
, size_t count
,int isSocket
);
310 ssize_t
read_all(tor_socket_t fd
, char *buf
, size_t count
, int isSocket
);
312 /** Status of an I/O stream. */
320 const char *stream_status_to_string(enum stream_status stream_status
);
322 enum stream_status
get_string_from_pipe(FILE *stream
, char *buf
, size_t count
);
324 MOCK_DECL(int,tor_unlink
,(const char *pathname
));
326 /** Return values from file_status(); see that function's documentation
328 typedef enum { FN_ERROR
, FN_NOENT
, FN_FILE
, FN_DIR
, FN_EMPTY
} file_status_t
;
329 file_status_t
file_status(const char *filename
);
331 /** Possible behaviors for check_private_dir() on encountering a nonexistent
332 * directory; see that function's documentation for details. */
333 typedef unsigned int cpd_check_t
;
335 #define CPD_CREATE (1u << 0)
336 #define CPD_CHECK (1u << 1)
337 #define CPD_GROUP_OK (1u << 2)
338 #define CPD_GROUP_READ (1u << 3)
339 #define CPD_CHECK_MODE_ONLY (1u << 4)
340 #define CPD_RELAX_DIRMODE_CHECK (1u << 5)
341 MOCK_DECL(int, check_private_dir
,
342 (const char *dirname
, cpd_check_t check
,
343 const char *effective_user
));
345 #define OPEN_FLAGS_REPLACE (O_WRONLY|O_CREAT|O_TRUNC)
346 #define OPEN_FLAGS_APPEND (O_WRONLY|O_CREAT|O_APPEND)
347 #define OPEN_FLAGS_DONT_REPLACE (O_CREAT|O_EXCL|O_APPEND|O_WRONLY)
348 typedef struct open_file_t open_file_t
;
349 int start_writing_to_file(const char *fname
, int open_flags
, int mode
,
350 open_file_t
**data_out
);
351 FILE *start_writing_to_stdio_file(const char *fname
, int open_flags
, int mode
,
352 open_file_t
**data_out
);
353 FILE *fdopen_file(open_file_t
*file_data
);
354 int finish_writing_to_file(open_file_t
*file_data
);
355 int abort_writing_to_file(open_file_t
*file_data
);
357 write_str_to_file
,(const char *fname
, const char *str
, int bin
));
359 write_bytes_to_file
,(const char *fname
, const char *str
, size_t len
,
361 /** An ad-hoc type to hold a string of characters and a count; used by
362 * write_chunks_to_file. */
363 typedef struct sized_chunk_t
{
367 int write_chunks_to_file(const char *fname
, const struct smartlist_t
*chunks
,
368 int bin
, int no_tempfile
);
369 int append_bytes_to_file(const char *fname
, const char *str
, size_t len
,
371 int write_bytes_to_new_file(const char *fname
, const char *str
, size_t len
,
374 /** Flag for read_file_to_str: open the file in binary mode. */
376 /** Flag for read_file_to_str: it's okay if the file doesn't exist. */
377 #define RFTS_IGNORE_MISSING 2
382 MOCK_DECL_ATTR(char *, read_file_to_str
,
383 (const char *filename
, int flags
, struct stat
*stat_out
),
385 char *read_file_to_str_until_eof(int fd
, size_t max_bytes_to_read
,
388 const char *unescape_string(const char *s
, char **result
, size_t *size_out
);
389 const char *parse_config_line_from_str_verbose(const char *line
,
390 char **key_out
, char **value_out
,
391 const char **err_out
);
392 char *expand_filename(const char *filename
);
393 MOCK_DECL(struct smartlist_t
*, tor_listdir
, (const char *dirname
));
394 int path_is_relative(const char *filename
);
396 /* Process helpers */
397 void start_daemon(void);
398 void finish_daemon(const char *desired_cwd
);
399 void write_pidfile(const char *filename
);
401 /* Port forwarding */
402 void tor_check_port_forwarding(const char *filename
,
403 struct smartlist_t
*ports_to_forward
,
406 typedef struct process_handle_t process_handle_t
;
407 typedef struct process_environment_t process_environment_t
;
408 int tor_spawn_background(const char *const filename
, const char **argv
,
409 process_environment_t
*env
,
410 process_handle_t
**process_handle_out
);
412 #define SPAWN_ERROR_MESSAGE "ERR: Failed to spawn background process - code "
415 HANDLE
load_windows_system_library(const TCHAR
*library_name
);
418 int environment_variable_names_equal(const char *s1
, const char *s2
);
420 /* DOCDOC process_environment_t */
421 struct process_environment_t
{
422 /** A pointer to a sorted empty-string-terminated sequence of
423 * NUL-terminated strings of the form "NAME=VALUE". */
424 char *windows_environment_block
;
425 /** A pointer to a NULL-terminated array of pointers to
426 * NUL-terminated strings of the form "NAME=VALUE". */
427 char **unixoid_environment_block
;
430 process_environment_t
*process_environment_make(struct smartlist_t
*env_vars
);
431 void process_environment_free(process_environment_t
*env
);
433 struct smartlist_t
*get_current_process_environment_variables(void);
435 void set_environment_variable_in_smartlist(struct smartlist_t
*env_vars
,
437 void (*free_old
)(void*),
440 /* Values of process_handle_t.status. PROCESS_STATUS_NOTRUNNING must be
441 * 0 because tor_check_port_forwarding depends on this being the initial
442 * statue of the static instance of process_handle_t */
443 #define PROCESS_STATUS_NOTRUNNING 0
444 #define PROCESS_STATUS_RUNNING 1
445 #define PROCESS_STATUS_ERROR -1
448 struct waitpid_callback_t
;
449 /** Structure to represent the state of a process with which Tor is
450 * communicating. The contents of this structure are private to util.c */
451 struct process_handle_t
{
452 /** One of the PROCESS_STATUS_* values */
458 PROCESS_INFORMATION pid
;
467 /** If the process has not given us a SIGCHLD yet, this has the
468 * waitpid_callback_t that gets invoked once it has. Otherwise this
470 struct waitpid_callback_t
*waitpid_cb
;
471 /** The exit status reported by waitpid. */
472 int waitpid_exit_status
;
477 /* Return values of tor_get_exit_code() */
478 #define PROCESS_EXIT_RUNNING 1
479 #define PROCESS_EXIT_EXITED 0
480 #define PROCESS_EXIT_ERROR -1
481 int tor_get_exit_code(process_handle_t
*process_handle
,
482 int block
, int *exit_code
);
483 int tor_split_lines(struct smartlist_t
*sl
, char *buf
, int len
);
485 ssize_t
tor_read_all_handle(HANDLE h
, char *buf
, size_t count
,
486 const process_handle_t
*process
);
488 ssize_t
tor_read_all_handle(FILE *h
, char *buf
, size_t count
,
489 const process_handle_t
*process
,
492 ssize_t
tor_read_all_from_process_stdout(
493 const process_handle_t
*process_handle
, char *buf
, size_t count
);
494 ssize_t
tor_read_all_from_process_stderr(
495 const process_handle_t
*process_handle
, char *buf
, size_t count
);
496 char *tor_join_win_cmdline(const char *argv
[]);
498 int tor_process_get_pid(process_handle_t
*process_handle
);
500 HANDLE
tor_process_get_stdout_pipe(process_handle_t
*process_handle
);
502 FILE *tor_process_get_stdout_pipe(process_handle_t
*process_handle
);
506 MOCK_DECL(struct smartlist_t
*,
507 tor_get_lines_from_handle
,(HANDLE
*handle
,
508 enum stream_status
*stream_status
));
510 MOCK_DECL(struct smartlist_t
*,
511 tor_get_lines_from_handle
,(FILE *handle
,
512 enum stream_status
*stream_status
));
516 tor_terminate_process(process_handle_t
*process_handle
);
519 tor_process_handle_destroy
,(process_handle_t
*process_handle
,
520 int also_terminate_process
));
522 /* ===== Insecure rng */
523 typedef struct tor_weak_rng_t
{
527 #define TOR_WEAK_RNG_INIT {383745623}
528 #define TOR_WEAK_RANDOM_MAX (INT_MAX)
529 void tor_init_weak_random(tor_weak_rng_t
*weak_rng
, unsigned seed
);
530 int32_t tor_weak_random(tor_weak_rng_t
*weak_rng
);
531 int32_t tor_weak_random_range(tor_weak_rng_t
*rng
, int32_t top
);
532 /** Randomly return true according to <b>rng</b> with probability 1 in
534 #define tor_weak_random_one_in_n(rng, n) (0==tor_weak_random_range((rng),(n)))
536 int format_hex_number_sigsafe(unsigned long x
, char *buf
, int max_len
);
537 int format_dec_number_sigsafe(unsigned long x
, char *buf
, int max_len
);
540 /* Prototypes for private functions only used by util.c (and unit tests) */
543 STATIC
int format_helper_exit_status(unsigned char child_state
,
544 int saved_errno
, char *hex_errno
);
546 /* Space for hex values of child state, a slash, saved_errno (with
547 leading minus) and newline (no null) */
548 #define HEX_ERRNO_SIZE (sizeof(char) * 2 + 1 + \
549 1 + sizeof(int) * 2 + 1)
554 #ifdef TOR_UNIT_TESTS
555 int size_mul_check__(const size_t x
, const size_t y
);
558 #define ARRAY_LENGTH(x) ((sizeof(x)) / sizeof(x[0]))