1 /* Copyright (c) 2003-2004, Roger Dingledine
2 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
3 * Copyright (c) 2007-2013, The Tor Project, Inc. */
4 /* See LICENSE for licensing information */
8 * \brief Headers for util.c
21 /* for the correct alias to struct stat */
32 /* Replace assert() with a variant that sends failures to the log before
33 * calling assert() normally.
36 /* Nobody should ever want to build with NDEBUG set. 99% of our asserts will
37 * be outside the critical path anyway, so it's silly to disable bug-checking
38 * throughout the entire program just because a few asserts are slowing you
39 * down. Profile, optimize the critical path, and keep debugging on.
41 * And I'm not just saying that because some of our asserts check
42 * security-critical properties.
44 #error "Sorry; we don't support building with NDEBUG."
47 /** Like assert(3), but send assertion failures to the log as well as to
49 #define tor_assert(expr) STMT_BEGIN \
50 if (PREDICT_UNLIKELY(!(expr))) { \
51 log_err(LD_BUG, "%s:%d: %s: Assertion %s failed; aborting.", \
52 SHORT_FILE__, __LINE__, __func__, #expr); \
53 fprintf(stderr,"%s:%d %s: Assertion %s failed; aborting.\n", \
54 SHORT_FILE__, __LINE__, __func__, #expr); \
58 /* If we're building with dmalloc, we want all of our memory allocation
59 * functions to take an extra file/line pair of arguments. If not, not.
60 * We define DMALLOC_PARAMS to the extra parameters to insert in the
61 * function prototypes, and DMALLOC_ARGS to the extra arguments to add
64 #define DMALLOC_PARAMS , const char *file, const int line
65 #define DMALLOC_ARGS , SHORT_FILE__, __LINE__
67 #define DMALLOC_PARAMS
71 /** Define this if you want Tor to crash when any problem comes up,
72 * so you can get a coredump and track things down. */
73 // #define tor_fragile_assert() tor_assert(0)
74 #define tor_fragile_assert()
76 /* Memory management */
77 void *tor_malloc_(size_t size DMALLOC_PARAMS
) ATTR_MALLOC
;
78 void *tor_malloc_zero_(size_t size DMALLOC_PARAMS
) ATTR_MALLOC
;
79 void *tor_calloc_(size_t nmemb
, size_t size DMALLOC_PARAMS
) ATTR_MALLOC
;
80 void *tor_realloc_(void *ptr
, size_t size DMALLOC_PARAMS
);
81 char *tor_strdup_(const char *s DMALLOC_PARAMS
) ATTR_MALLOC
ATTR_NONNULL((1));
82 char *tor_strndup_(const char *s
, size_t n DMALLOC_PARAMS
)
83 ATTR_MALLOC
ATTR_NONNULL((1));
84 void *tor_memdup_(const void *mem
, size_t len DMALLOC_PARAMS
)
85 ATTR_MALLOC
ATTR_NONNULL((1));
86 void *tor_memdup_nulterm_(const void *mem
, size_t len DMALLOC_PARAMS
)
87 ATTR_MALLOC
ATTR_NONNULL((1));
88 void tor_free_(void *mem
);
90 extern int dmalloc_free(const char *file
, const int line
, void *pnt
,
92 #define tor_free(p) STMT_BEGIN \
93 if (PREDICT_LIKELY((p)!=NULL)) { \
94 dmalloc_free(SHORT_FILE__, __LINE__, (p), 0); \
99 /** Release memory allocated by tor_malloc, tor_realloc, tor_strdup, etc.
100 * Unlike the free() function, tor_free() will still work on NULL pointers,
101 * and it sets the pointer value to NULL after freeing it.
103 * This is a macro. If you need a function pointer to release memory from
104 * tor_malloc(), use tor_free_().
106 #define tor_free(p) STMT_BEGIN \
107 if (PREDICT_LIKELY((p)!=NULL)) { \
114 #define tor_malloc(size) tor_malloc_(size DMALLOC_ARGS)
115 #define tor_malloc_zero(size) tor_malloc_zero_(size DMALLOC_ARGS)
116 #define tor_calloc(nmemb,size) tor_calloc_(nmemb, size DMALLOC_ARGS)
117 #define tor_realloc(ptr, size) tor_realloc_(ptr, size DMALLOC_ARGS)
118 #define tor_strdup(s) tor_strdup_(s DMALLOC_ARGS)
119 #define tor_strndup(s, n) tor_strndup_(s, n DMALLOC_ARGS)
120 #define tor_memdup(s, n) tor_memdup_(s, n DMALLOC_ARGS)
121 #define tor_memdup_nulterm(s, n) tor_memdup_nulterm_(s, n DMALLOC_ARGS)
123 void tor_log_mallinfo(int severity
);
125 /** Return the offset of <b>member</b> within the type <b>tp</b>, in bytes */
126 #if defined(__GNUC__) && __GNUC__ > 3
127 #define STRUCT_OFFSET(tp, member) __builtin_offsetof(tp, member)
129 #define STRUCT_OFFSET(tp, member) \
130 ((off_t) (((char*)&((tp*)0)->member)-(char*)0))
133 /** Macro: yield a pointer to the field at position <b>off</b> within the
134 * structure <b>st</b>. Example:
136 * struct a { int foo; int bar; } x;
137 * off_t bar_offset = STRUCT_OFFSET(struct a, bar);
138 * int *bar_p = STRUCT_VAR_P(&x, bar_offset);
142 #define STRUCT_VAR_P(st, off) ((void*) ( ((char*)(st)) + (off) ) )
144 /** Macro: yield a pointer to an enclosing structure given a pointer to
145 * a substructure at offset <b>off</b>. Example:
147 * struct base { ... };
148 * struct subtype { int x; struct base b; } x;
149 * struct base *bp = &x.base;
150 * struct *sp = SUBTYPE_P(bp, struct subtype, b);
153 #define SUBTYPE_P(p, subtype, basemember) \
154 ((void*) ( ((char*)(p)) - STRUCT_OFFSET(subtype, basemember) ))
157 /** Macro: true if two values have the same boolean value. */
158 #define bool_eq(a,b) (!(a)==!(b))
159 /** Macro: true if two values have different boolean values. */
160 #define bool_neq(a,b) (!(a)!=!(b))
163 double tor_mathlog(double d
) ATTR_CONST
;
164 long tor_lround(double d
) ATTR_CONST
;
165 int64_t tor_llround(double d
) ATTR_CONST
;
166 int tor_log2(uint64_t u64
) ATTR_CONST
;
167 uint64_t round_to_power_of_2(uint64_t u64
);
168 unsigned round_to_next_multiple_of(unsigned number
, unsigned divisor
);
169 uint32_t round_uint32_to_next_multiple_of(uint32_t number
, uint32_t divisor
);
170 uint64_t round_uint64_to_next_multiple_of(uint64_t number
, uint64_t divisor
);
171 int n_bits_set_u8(uint8_t v
);
173 /* Compute the CEIL of <b>a</b> divided by <b>b</b>, for nonnegative <b>a</b>
174 * and positive <b>b</b>. Works on integer types only. Not defined if a+b can
176 #define CEIL_DIV(a,b) (((a)+(b)-1)/(b))
178 /* Return <b>v</b> if it's between <b>min</b> and <b>max</b>. Otherwise
179 * return <b>min</b> if <b>v</b> is smaller than <b>min</b>, or <b>max</b> if
180 * <b>b</b> is larger than <b>max</b>.
182 * Requires that <b>min</b> is no more than <b>max</b>. May evaluate any of
183 * its arguments more than once! */
184 #define CLAMP(min,v,max) \
185 ( ((v) < (min)) ? (min) : \
186 ((v) > (max)) ? (max) : \
189 /* String manipulation */
191 /** Allowable characters in a hexadecimal string. */
192 #define HEX_CHARACTERS "0123456789ABCDEFabcdef"
193 void tor_strlower(char *s
) ATTR_NONNULL((1));
194 void tor_strupper(char *s
) ATTR_NONNULL((1));
195 int tor_strisprint(const char *s
) ATTR_NONNULL((1));
196 int tor_strisnonupper(const char *s
) ATTR_NONNULL((1));
197 int strcmp_opt(const char *s1
, const char *s2
);
198 int strcmpstart(const char *s1
, const char *s2
) ATTR_NONNULL((1,2));
199 int strcmp_len(const char *s1
, const char *s2
, size_t len
) ATTR_NONNULL((1,2));
200 int strcasecmpstart(const char *s1
, const char *s2
) ATTR_NONNULL((1,2));
201 int strcmpend(const char *s1
, const char *s2
) ATTR_NONNULL((1,2));
202 int strcasecmpend(const char *s1
, const char *s2
) ATTR_NONNULL((1,2));
203 int fast_memcmpstart(const void *mem
, size_t memlen
, const char *prefix
);
204 void tor_strclear(char *s
);
206 void tor_strstrip(char *s
, const char *strip
) ATTR_NONNULL((1,2));
207 long tor_parse_long(const char *s
, int base
, long min
,
208 long max
, int *ok
, char **next
);
209 unsigned long tor_parse_ulong(const char *s
, int base
, unsigned long min
,
210 unsigned long max
, int *ok
, char **next
);
211 double tor_parse_double(const char *s
, double min
, double max
, int *ok
,
213 uint64_t tor_parse_uint64(const char *s
, int base
, uint64_t min
,
214 uint64_t max
, int *ok
, char **next
);
215 const char *hex_str(const char *from
, size_t fromlen
) ATTR_NONNULL((1));
216 const char *eat_whitespace(const char *s
);
217 const char *eat_whitespace_eos(const char *s
, const char *eos
);
218 const char *eat_whitespace_no_nl(const char *s
);
219 const char *eat_whitespace_eos_no_nl(const char *s
, const char *eos
);
220 const char *find_whitespace(const char *s
);
221 const char *find_whitespace_eos(const char *s
, const char *eos
);
222 const char *find_str_at_start_of_line(const char *haystack
,
224 int string_is_C_identifier(const char *string
);
226 int tor_mem_is_zero(const char *mem
, size_t len
);
227 int tor_digest_is_zero(const char *digest
);
228 int tor_digest256_is_zero(const char *digest
);
229 char *esc_for_log(const char *string
) ATTR_MALLOC
;
230 const char *escaped(const char *string
);
232 int tor_vsscanf(const char *buf
, const char *pattern
, va_list ap
)
234 __attribute__((format(scanf
, 2, 0)))
237 int tor_sscanf(const char *buf
, const char *pattern
, ...)
239 __attribute__((format(scanf
, 2, 3)))
243 void smartlist_add_asprintf(struct smartlist_t
*sl
, const char *pattern
, ...)
245 void smartlist_add_vasprintf(struct smartlist_t
*sl
, const char *pattern
,
249 int hex_decode_digit(char c
);
250 void base16_encode(char *dest
, size_t destlen
, const char *src
, size_t srclen
);
251 int base16_decode(char *dest
, size_t destlen
, const char *src
, size_t srclen
);
254 long tv_udiff(const struct timeval
*start
, const struct timeval
*end
);
255 long tv_mdiff(const struct timeval
*start
, const struct timeval
*end
);
256 int tor_timegm(const struct tm
*tm
, time_t *time_out
);
257 #define RFC1123_TIME_LEN 29
258 void format_rfc1123_time(char *buf
, time_t t
);
259 int parse_rfc1123_time(const char *buf
, time_t *t
);
260 #define ISO_TIME_LEN 19
261 #define ISO_TIME_USEC_LEN (ISO_TIME_LEN+7)
262 void format_local_iso_time(char *buf
, time_t t
);
263 void format_iso_time(char *buf
, time_t t
);
264 void format_iso_time_nospace(char *buf
, time_t t
);
265 void format_iso_time_nospace_usec(char *buf
, const struct timeval
*tv
);
266 int parse_iso_time(const char *buf
, time_t *t
);
267 int parse_http_time(const char *buf
, struct tm
*tm
);
268 int format_time_interval(char *out
, size_t out_len
, long interval
);
272 #define approx_time() time(NULL)
273 #define update_approx_time(t) STMT_NIL
275 time_t approx_time(void);
276 void update_approx_time(time_t now
);
281 /** A ratelim_t remembers how often an event is occurring, and how often
282 * it's allowed to occur. Typical usage is something like:
285 if (possibly_very_frequent_event()) {
286 const int INTERVAL = 300;
287 static ratelim_t warning_limit = RATELIM_INIT(INTERVAL);
289 if ((m = rate_limit_log(&warning_limit, approx_time()))) {
290 log_warn(LD_GENERAL, "The event occurred!%s", m);
296 As a convenience wrapper for logging, you can replace the above with:
298 if (possibly_very_frequent_event()) {
299 static ratelim_t warning_limit = RATELIM_INIT(300);
300 log_fn_ratelim(&warning_limit, LOG_WARN, LD_GENERAL,
301 "The event occurred!");
305 typedef struct ratelim_t
{
308 int n_calls_since_last_time
;
311 #define RATELIM_INIT(r) { (r), 0, 0 }
313 char *rate_limit_log(ratelim_t
*lim
, time_t now
);
316 ssize_t
write_all(tor_socket_t fd
, const char *buf
, size_t count
,int isSocket
);
317 ssize_t
read_all(tor_socket_t fd
, char *buf
, size_t count
, int isSocket
);
319 /** Status of an I/O stream. */
327 const char *stream_status_to_string(enum stream_status stream_status
);
329 enum stream_status
get_string_from_pipe(FILE *stream
, char *buf
, size_t count
);
331 /** Return values from file_status(); see that function's documentation
333 typedef enum { FN_ERROR
, FN_NOENT
, FN_FILE
, FN_DIR
} file_status_t
;
334 file_status_t
file_status(const char *filename
);
336 /** Possible behaviors for check_private_dir() on encountering a nonexistent
337 * directory; see that function's documentation for details. */
338 typedef unsigned int cpd_check_t
;
342 #define CPD_GROUP_OK 4
343 #define CPD_CHECK_MODE_ONLY 8
344 int check_private_dir(const char *dirname
, cpd_check_t check
,
345 const char *effective_user
);
346 #define OPEN_FLAGS_REPLACE (O_WRONLY|O_CREAT|O_TRUNC)
347 #define OPEN_FLAGS_APPEND (O_WRONLY|O_CREAT|O_APPEND)
348 #define OPEN_FLAGS_DONT_REPLACE (O_CREAT|O_EXCL|O_APPEND|O_WRONLY)
349 typedef struct open_file_t open_file_t
;
350 int start_writing_to_file(const char *fname
, int open_flags
, int mode
,
351 open_file_t
**data_out
);
352 FILE *start_writing_to_stdio_file(const char *fname
, int open_flags
, int mode
,
353 open_file_t
**data_out
);
354 FILE *fdopen_file(open_file_t
*file_data
);
355 int finish_writing_to_file(open_file_t
*file_data
);
356 int abort_writing_to_file(open_file_t
*file_data
);
357 int write_str_to_file(const char *fname
, const char *str
, int bin
);
358 int write_bytes_to_file(const char *fname
, const char *str
, size_t len
,
360 /** An ad-hoc type to hold a string of characters and a count; used by
361 * write_chunks_to_file. */
362 typedef struct sized_chunk_t
{
366 int write_chunks_to_file(const char *fname
, const struct smartlist_t
*chunks
,
368 int append_bytes_to_file(const char *fname
, const char *str
, size_t len
,
370 int write_bytes_to_new_file(const char *fname
, const char *str
, size_t len
,
373 /** Flag for read_file_to_str: open the file in binary mode. */
375 /** Flag for read_file_to_str: it's okay if the file doesn't exist. */
376 #define RFTS_IGNORE_MISSING 2
381 char *read_file_to_str(const char *filename
, int flags
, struct stat
*stat_out
)
383 char *read_file_to_str_until_eof(int fd
, size_t max_bytes_to_read
,
386 const char *parse_config_line_from_str_verbose(const char *line
,
387 char **key_out
, char **value_out
,
388 const char **err_out
);
389 #define parse_config_line_from_str(line,key_out,value_out) \
390 parse_config_line_from_str_verbose((line),(key_out),(value_out),NULL)
391 char *expand_filename(const char *filename
);
392 struct smartlist_t
*tor_listdir(const char *dirname
);
393 int path_is_relative(const char *filename
);
395 /* Process helpers */
396 void start_daemon(void);
397 void finish_daemon(const char *desired_cwd
);
398 void write_pidfile(char *filename
);
400 /* Port forwarding */
401 void tor_check_port_forwarding(const char *filename
,
402 struct smartlist_t
*ports_to_forward
,
405 typedef struct process_handle_t process_handle_t
;
406 typedef struct process_environment_t process_environment_t
;
407 int tor_spawn_background(const char *const filename
, const char **argv
,
408 process_environment_t
*env
,
409 process_handle_t
**process_handle_out
);
411 #define SPAWN_ERROR_MESSAGE "ERR: Failed to spawn background process - code "
414 HANDLE
load_windows_system_library(const TCHAR
*library_name
);
417 int environment_variable_names_equal(const char *s1
, const char *s2
);
419 /* DOCDOC process_environment_t */
420 struct process_environment_t
{
421 /** A pointer to a sorted empty-string-terminated sequence of
422 * NUL-terminated strings of the form "NAME=VALUE". */
423 char *windows_environment_block
;
424 /** A pointer to a NULL-terminated array of pointers to
425 * NUL-terminated strings of the form "NAME=VALUE". */
426 char **unixoid_environment_block
;
429 process_environment_t
*process_environment_make(struct smartlist_t
*env_vars
);
430 void process_environment_free(process_environment_t
*env
);
432 struct smartlist_t
*get_current_process_environment_variables(void);
434 void set_environment_variable_in_smartlist(struct smartlist_t
*env_vars
,
436 void (*free_old
)(void*),
439 /* Values of process_handle_t.status. PROCESS_STATUS_NOTRUNNING must be
440 * 0 because tor_check_port_forwarding depends on this being the initial
441 * statue of the static instance of process_handle_t */
442 #define PROCESS_STATUS_NOTRUNNING 0
443 #define PROCESS_STATUS_RUNNING 1
444 #define PROCESS_STATUS_ERROR -1
447 /** Structure to represent the state of a process with which Tor is
448 * communicating. The contents of this structure are private to util.c */
449 struct process_handle_t
{
450 /** One of the PROCESS_STATUS_* values */
455 PROCESS_INFORMATION pid
;
466 /* Return values of tor_get_exit_code() */
467 #define PROCESS_EXIT_RUNNING 1
468 #define PROCESS_EXIT_EXITED 0
469 #define PROCESS_EXIT_ERROR -1
470 int tor_get_exit_code(const process_handle_t
*process_handle
,
471 int block
, int *exit_code
);
472 int tor_split_lines(struct smartlist_t
*sl
, char *buf
, int len
);
474 ssize_t
tor_read_all_handle(HANDLE h
, char *buf
, size_t count
,
475 const process_handle_t
*process
);
477 ssize_t
tor_read_all_handle(FILE *h
, char *buf
, size_t count
,
478 const process_handle_t
*process
,
481 ssize_t
tor_read_all_from_process_stdout(
482 const process_handle_t
*process_handle
, char *buf
, size_t count
);
483 ssize_t
tor_read_all_from_process_stderr(
484 const process_handle_t
*process_handle
, char *buf
, size_t count
);
485 char *tor_join_win_cmdline(const char *argv
[]);
487 int tor_process_get_pid(process_handle_t
*process_handle
);
489 HANDLE
tor_process_get_stdout_pipe(process_handle_t
*process_handle
);
491 FILE *tor_process_get_stdout_pipe(process_handle_t
*process_handle
);
496 tor_get_lines_from_handle(HANDLE
*handle
,
497 enum stream_status
*stream_status
);
500 tor_get_lines_from_handle(FILE *handle
,
501 enum stream_status
*stream_status
);
504 int tor_terminate_process(process_handle_t
*process_handle
);
505 void tor_process_handle_destroy(process_handle_t
*process_handle
,
506 int also_terminate_process
);
508 /* ===== Insecure rng */
509 typedef struct tor_weak_rng_t
{
513 #define TOR_WEAK_RNG_INIT {383745623}
514 #define TOR_WEAK_RANDOM_MAX (INT_MAX)
515 void tor_init_weak_random(tor_weak_rng_t
*weak_rng
, unsigned seed
);
516 int32_t tor_weak_random(tor_weak_rng_t
*weak_rng
);
517 int32_t tor_weak_random_range(tor_weak_rng_t
*rng
, int32_t top
);
518 /** Randomly return true according to <b>rng</b> with probability 1 in
520 #define tor_weak_random_one_in_n(rng, n) (0==tor_weak_random_range((rng),(n)))
523 /* Prototypes for private functions only used by util.c (and unit tests) */
525 int format_hex_number_for_helper_exit_status(unsigned int x
, char *buf
,
527 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)
536 const char *libor_get_digests(void);