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 void tor_log_mallinfo(int severity
);
104 /** Return the offset of <b>member</b> within the type <b>tp</b>, in bytes */
105 #if defined(__GNUC__) && __GNUC__ > 3
106 #define STRUCT_OFFSET(tp, member) __builtin_offsetof(tp, member)
108 #define STRUCT_OFFSET(tp, member) \
109 ((off_t) (((char*)&((tp*)0)->member)-(char*)0))
112 /** Macro: yield a pointer to the field at position <b>off</b> within the
113 * structure <b>st</b>. Example:
115 * struct a { int foo; int bar; } x;
116 * off_t bar_offset = STRUCT_OFFSET(struct a, bar);
117 * int *bar_p = STRUCT_VAR_P(&x, bar_offset);
121 #define STRUCT_VAR_P(st, off) ((void*) ( ((char*)(st)) + (off) ) )
123 /** Macro: yield a pointer to an enclosing structure given a pointer to
124 * a substructure at offset <b>off</b>. Example:
126 * struct base { ... };
127 * struct subtype { int x; struct base b; } x;
128 * struct base *bp = &x.base;
129 * struct *sp = SUBTYPE_P(bp, struct subtype, b);
132 #define SUBTYPE_P(p, subtype, basemember) \
133 ((void*) ( ((char*)(p)) - STRUCT_OFFSET(subtype, basemember) ))
136 /** Macro: true if two values have the same boolean value. */
137 #define bool_eq(a,b) (!(a)==!(b))
138 /** Macro: true if two values have different boolean values. */
139 #define bool_neq(a,b) (!(a)!=!(b))
142 double tor_mathlog(double d
) ATTR_CONST
;
143 long tor_lround(double d
) ATTR_CONST
;
144 int64_t tor_llround(double d
) ATTR_CONST
;
145 int tor_log2(uint64_t u64
) ATTR_CONST
;
146 uint64_t round_to_power_of_2(uint64_t u64
);
147 unsigned round_to_next_multiple_of(unsigned number
, unsigned divisor
);
148 uint32_t round_uint32_to_next_multiple_of(uint32_t number
, uint32_t divisor
);
149 uint64_t round_uint64_to_next_multiple_of(uint64_t number
, uint64_t divisor
);
150 int64_t sample_laplace_distribution(double mu
, double b
, double p
);
151 int64_t add_laplace_noise(int64_t signal
, double random
, double delta_f
,
153 int n_bits_set_u8(uint8_t v
);
154 int64_t clamp_double_to_int64(double number
);
156 /* Compute the CEIL of <b>a</b> divided by <b>b</b>, for nonnegative <b>a</b>
157 * and positive <b>b</b>. Works on integer types only. Not defined if a+b can
159 #define CEIL_DIV(a,b) (((a)+(b)-1)/(b))
161 /* Return <b>v</b> if it's between <b>min</b> and <b>max</b>. Otherwise
162 * return <b>min</b> if <b>v</b> is smaller than <b>min</b>, or <b>max</b> if
163 * <b>b</b> is larger than <b>max</b>.
165 * Requires that <b>min</b> is no more than <b>max</b>. May evaluate any of
166 * its arguments more than once! */
167 #define CLAMP(min,v,max) \
168 ( ((v) < (min)) ? (min) : \
169 ((v) > (max)) ? (max) : \
172 /* String manipulation */
174 /** Allowable characters in a hexadecimal string. */
175 #define HEX_CHARACTERS "0123456789ABCDEFabcdef"
176 void tor_strlower(char *s
) ATTR_NONNULL((1));
177 void tor_strupper(char *s
) ATTR_NONNULL((1));
178 int tor_strisprint(const char *s
) ATTR_NONNULL((1));
179 int tor_strisnonupper(const char *s
) ATTR_NONNULL((1));
180 int strcmp_opt(const char *s1
, const char *s2
);
181 int strcmpstart(const char *s1
, const char *s2
) ATTR_NONNULL((1,2));
182 int strcmp_len(const char *s1
, const char *s2
, size_t len
) ATTR_NONNULL((1,2));
183 int strcasecmpstart(const char *s1
, const char *s2
) ATTR_NONNULL((1,2));
184 int strcmpend(const char *s1
, const char *s2
) ATTR_NONNULL((1,2));
185 int strcasecmpend(const char *s1
, const char *s2
) ATTR_NONNULL((1,2));
186 int fast_memcmpstart(const void *mem
, size_t memlen
, const char *prefix
);
188 void tor_strstrip(char *s
, const char *strip
) ATTR_NONNULL((1,2));
189 long tor_parse_long(const char *s
, int base
, long min
,
190 long max
, int *ok
, char **next
);
191 unsigned long tor_parse_ulong(const char *s
, int base
, unsigned long min
,
192 unsigned long max
, int *ok
, char **next
);
193 double tor_parse_double(const char *s
, double min
, double max
, int *ok
,
195 uint64_t tor_parse_uint64(const char *s
, int base
, uint64_t min
,
196 uint64_t max
, int *ok
, char **next
);
197 const char *hex_str(const char *from
, size_t fromlen
) ATTR_NONNULL((1));
198 const char *eat_whitespace(const char *s
);
199 const char *eat_whitespace_eos(const char *s
, const char *eos
);
200 const char *eat_whitespace_no_nl(const char *s
);
201 const char *eat_whitespace_eos_no_nl(const char *s
, const char *eos
);
202 const char *find_whitespace(const char *s
);
203 const char *find_whitespace_eos(const char *s
, const char *eos
);
204 const char *find_str_at_start_of_line(const char *haystack
,
206 int string_is_C_identifier(const char *string
);
207 int string_is_key_value(int severity
, const char *string
);
208 int string_is_valid_hostname(const char *string
);
209 int string_is_valid_ipv4_address(const char *string
);
210 int string_is_valid_ipv6_address(const char *string
);
212 int tor_mem_is_zero(const char *mem
, size_t len
);
213 int tor_digest_is_zero(const char *digest
);
214 int tor_digest256_is_zero(const char *digest
);
215 char *esc_for_log(const char *string
) ATTR_MALLOC
;
216 char *esc_for_log_len(const char *chars
, size_t n
) ATTR_MALLOC
;
217 const char *escaped(const char *string
);
219 char *tor_escape_str_for_pt_args(const char *string
,
220 const char *chars_to_escape
);
223 int tor_vsscanf(const char *buf
, const char *pattern
, va_list ap
) \
225 int tor_sscanf(const char *buf
, const char *pattern
, ...)
228 void smartlist_add_asprintf(struct smartlist_t
*sl
, const char *pattern
, ...)
230 void smartlist_add_vasprintf(struct smartlist_t
*sl
, const char *pattern
,
235 long tv_udiff(const struct timeval
*start
, const struct timeval
*end
);
236 long tv_mdiff(const struct timeval
*start
, const struct timeval
*end
);
237 int64_t tv_to_msec(const struct timeval
*tv
);
238 int tor_timegm(const struct tm
*tm
, time_t *time_out
);
239 #define RFC1123_TIME_LEN 29
240 void format_rfc1123_time(char *buf
, time_t t
);
241 int parse_rfc1123_time(const char *buf
, time_t *t
);
242 #define ISO_TIME_LEN 19
243 #define ISO_TIME_USEC_LEN (ISO_TIME_LEN+7)
244 void format_local_iso_time(char *buf
, time_t t
);
245 void format_iso_time(char *buf
, time_t t
);
246 void format_iso_time_nospace(char *buf
, time_t t
);
247 void format_iso_time_nospace_usec(char *buf
, const struct timeval
*tv
);
248 int parse_iso_time_(const char *cp
, time_t *t
, int strict
);
249 int parse_iso_time(const char *buf
, time_t *t
);
250 int parse_http_time(const char *buf
, struct tm
*tm
);
251 int format_time_interval(char *out
, size_t out_len
, long interval
);
255 #define approx_time() time(NULL)
256 #define update_approx_time(t) STMT_NIL
258 time_t approx_time(void);
259 void update_approx_time(time_t now
);
264 /** A ratelim_t remembers how often an event is occurring, and how often
265 * it's allowed to occur. Typical usage is something like:
268 if (possibly_very_frequent_event()) {
269 const int INTERVAL = 300;
270 static ratelim_t warning_limit = RATELIM_INIT(INTERVAL);
272 if ((m = rate_limit_log(&warning_limit, approx_time()))) {
273 log_warn(LD_GENERAL, "The event occurred!%s", m);
279 As a convenience wrapper for logging, you can replace the above with:
281 if (possibly_very_frequent_event()) {
282 static ratelim_t warning_limit = RATELIM_INIT(300);
283 log_fn_ratelim(&warning_limit, LOG_WARN, LD_GENERAL,
284 "The event occurred!");
288 typedef struct ratelim_t
{
291 int n_calls_since_last_time
;
294 #define RATELIM_INIT(r) { (r), 0, 0 }
296 char *rate_limit_log(ratelim_t
*lim
, time_t now
);
299 ssize_t
write_all(tor_socket_t fd
, const char *buf
, size_t count
,int isSocket
);
300 ssize_t
read_all(tor_socket_t fd
, char *buf
, size_t count
, int isSocket
);
302 /** Status of an I/O stream. */
310 const char *stream_status_to_string(enum stream_status stream_status
);
312 enum stream_status
get_string_from_pipe(FILE *stream
, char *buf
, size_t count
);
314 /** Return values from file_status(); see that function's documentation
316 typedef enum { FN_ERROR
, FN_NOENT
, FN_FILE
, FN_DIR
, FN_EMPTY
} file_status_t
;
317 file_status_t
file_status(const char *filename
);
319 /** Possible behaviors for check_private_dir() on encountering a nonexistent
320 * directory; see that function's documentation for details. */
321 typedef unsigned int cpd_check_t
;
323 #define CPD_CREATE (1u << 0)
324 #define CPD_CHECK (1u << 1)
325 #define CPD_GROUP_OK (1u << 2)
326 #define CPD_GROUP_READ (1u << 3)
327 #define CPD_CHECK_MODE_ONLY (1u << 4)
328 #define CPD_RELAX_DIRMODE_CHECK (1u << 5)
329 int check_private_dir(const char *dirname
, cpd_check_t check
,
330 const char *effective_user
);
332 #define OPEN_FLAGS_REPLACE (O_WRONLY|O_CREAT|O_TRUNC)
333 #define OPEN_FLAGS_APPEND (O_WRONLY|O_CREAT|O_APPEND)
334 #define OPEN_FLAGS_DONT_REPLACE (O_CREAT|O_EXCL|O_APPEND|O_WRONLY)
335 typedef struct open_file_t open_file_t
;
336 int start_writing_to_file(const char *fname
, int open_flags
, int mode
,
337 open_file_t
**data_out
);
338 FILE *start_writing_to_stdio_file(const char *fname
, int open_flags
, int mode
,
339 open_file_t
**data_out
);
340 FILE *fdopen_file(open_file_t
*file_data
);
341 int finish_writing_to_file(open_file_t
*file_data
);
342 int abort_writing_to_file(open_file_t
*file_data
);
343 int write_str_to_file(const char *fname
, const char *str
, int bin
);
345 write_bytes_to_file
,(const char *fname
, const char *str
, size_t len
,
347 /** An ad-hoc type to hold a string of characters and a count; used by
348 * write_chunks_to_file. */
349 typedef struct sized_chunk_t
{
353 int write_chunks_to_file(const char *fname
, const struct smartlist_t
*chunks
,
354 int bin
, int no_tempfile
);
355 int append_bytes_to_file(const char *fname
, const char *str
, size_t len
,
357 int write_bytes_to_new_file(const char *fname
, const char *str
, size_t len
,
360 /** Flag for read_file_to_str: open the file in binary mode. */
362 /** Flag for read_file_to_str: it's okay if the file doesn't exist. */
363 #define RFTS_IGNORE_MISSING 2
368 char *read_file_to_str(const char *filename
, int flags
, struct stat
*stat_out
)
370 char *read_file_to_str_until_eof(int fd
, size_t max_bytes_to_read
,
373 const char *parse_config_line_from_str_verbose(const char *line
,
374 char **key_out
, char **value_out
,
375 const char **err_out
);
376 char *expand_filename(const char *filename
);
377 struct smartlist_t
*tor_listdir(const char *dirname
);
378 int path_is_relative(const char *filename
);
380 /* Process helpers */
381 void start_daemon(void);
382 void finish_daemon(const char *desired_cwd
);
383 void write_pidfile(const char *filename
);
385 /* Port forwarding */
386 void tor_check_port_forwarding(const char *filename
,
387 struct smartlist_t
*ports_to_forward
,
390 typedef struct process_handle_t process_handle_t
;
391 typedef struct process_environment_t process_environment_t
;
392 int tor_spawn_background(const char *const filename
, const char **argv
,
393 process_environment_t
*env
,
394 process_handle_t
**process_handle_out
);
396 #define SPAWN_ERROR_MESSAGE "ERR: Failed to spawn background process - code "
399 HANDLE
load_windows_system_library(const TCHAR
*library_name
);
402 int environment_variable_names_equal(const char *s1
, const char *s2
);
404 /* DOCDOC process_environment_t */
405 struct process_environment_t
{
406 /** A pointer to a sorted empty-string-terminated sequence of
407 * NUL-terminated strings of the form "NAME=VALUE". */
408 char *windows_environment_block
;
409 /** A pointer to a NULL-terminated array of pointers to
410 * NUL-terminated strings of the form "NAME=VALUE". */
411 char **unixoid_environment_block
;
414 process_environment_t
*process_environment_make(struct smartlist_t
*env_vars
);
415 void process_environment_free(process_environment_t
*env
);
417 struct smartlist_t
*get_current_process_environment_variables(void);
419 void set_environment_variable_in_smartlist(struct smartlist_t
*env_vars
,
421 void (*free_old
)(void*),
424 /* Values of process_handle_t.status. PROCESS_STATUS_NOTRUNNING must be
425 * 0 because tor_check_port_forwarding depends on this being the initial
426 * statue of the static instance of process_handle_t */
427 #define PROCESS_STATUS_NOTRUNNING 0
428 #define PROCESS_STATUS_RUNNING 1
429 #define PROCESS_STATUS_ERROR -1
432 struct waitpid_callback_t
;
433 /** Structure to represent the state of a process with which Tor is
434 * communicating. The contents of this structure are private to util.c */
435 struct process_handle_t
{
436 /** One of the PROCESS_STATUS_* values */
442 PROCESS_INFORMATION pid
;
451 /** If the process has not given us a SIGCHLD yet, this has the
452 * waitpid_callback_t that gets invoked once it has. Otherwise this
454 struct waitpid_callback_t
*waitpid_cb
;
455 /** The exit status reported by waitpid. */
456 int waitpid_exit_status
;
461 /* Return values of tor_get_exit_code() */
462 #define PROCESS_EXIT_RUNNING 1
463 #define PROCESS_EXIT_EXITED 0
464 #define PROCESS_EXIT_ERROR -1
465 int tor_get_exit_code(process_handle_t
*process_handle
,
466 int block
, int *exit_code
);
467 int tor_split_lines(struct smartlist_t
*sl
, char *buf
, int len
);
469 ssize_t
tor_read_all_handle(HANDLE h
, char *buf
, size_t count
,
470 const process_handle_t
*process
);
472 ssize_t
tor_read_all_handle(FILE *h
, char *buf
, size_t count
,
473 const process_handle_t
*process
,
476 ssize_t
tor_read_all_from_process_stdout(
477 const process_handle_t
*process_handle
, char *buf
, size_t count
);
478 ssize_t
tor_read_all_from_process_stderr(
479 const process_handle_t
*process_handle
, char *buf
, size_t count
);
480 char *tor_join_win_cmdline(const char *argv
[]);
482 int tor_process_get_pid(process_handle_t
*process_handle
);
484 HANDLE
tor_process_get_stdout_pipe(process_handle_t
*process_handle
);
486 FILE *tor_process_get_stdout_pipe(process_handle_t
*process_handle
);
490 MOCK_DECL(struct smartlist_t
*,
491 tor_get_lines_from_handle
,(HANDLE
*handle
,
492 enum stream_status
*stream_status
));
494 MOCK_DECL(struct smartlist_t
*,
495 tor_get_lines_from_handle
,(FILE *handle
,
496 enum stream_status
*stream_status
));
500 tor_terminate_process(process_handle_t
*process_handle
);
503 tor_process_handle_destroy
,(process_handle_t
*process_handle
,
504 int also_terminate_process
));
506 /* ===== Insecure rng */
507 typedef struct tor_weak_rng_t
{
511 #define TOR_WEAK_RNG_INIT {383745623}
512 #define TOR_WEAK_RANDOM_MAX (INT_MAX)
513 void tor_init_weak_random(tor_weak_rng_t
*weak_rng
, unsigned seed
);
514 int32_t tor_weak_random(tor_weak_rng_t
*weak_rng
);
515 int32_t tor_weak_random_range(tor_weak_rng_t
*rng
, int32_t top
);
516 /** Randomly return true according to <b>rng</b> with probability 1 in
518 #define tor_weak_random_one_in_n(rng, n) (0==tor_weak_random_range((rng),(n)))
520 int format_hex_number_sigsafe(unsigned long x
, char *buf
, int max_len
);
521 int format_dec_number_sigsafe(unsigned long x
, char *buf
, int max_len
);
524 /* Prototypes for private functions only used by util.c (and unit tests) */
527 STATIC
int format_helper_exit_status(unsigned char child_state
,
528 int saved_errno
, char *hex_errno
);
530 /* Space for hex values of child state, a slash, saved_errno (with
531 leading minus) and newline (no null) */
532 #define HEX_ERRNO_SIZE (sizeof(char) * 2 + 1 + \
533 1 + sizeof(int) * 2 + 1)
538 #ifdef TOR_UNIT_TESTS
539 int size_mul_check__(const size_t x
, const size_t y
);
542 #define ARRAY_LENGTH(x) ((sizeof(x)) / sizeof(x[0]))