1 /* Copyright (c) 2003-2004, Roger Dingledine
2 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
3 * Copyright (c) 2007-2011, The Tor Project, Inc. */
4 /* See LICENSE for licensing information */
8 * \brief Headers for util.c
28 /* Replace assert() with a variant that sends failures to the log before
29 * calling assert() normally.
32 /* Nobody should ever want to build with NDEBUG set. 99% of our asserts will
33 * be outside the critical path anyway, so it's silly to disable bug-checking
34 * throughout the entire program just because a few asserts are slowing you
35 * down. Profile, optimize the critical path, and keep debugging on.
37 * And I'm not just saying that because some of our asserts check
38 * security-critical properties.
40 #error "Sorry; we don't support building with NDEBUG."
43 /** Like assert(3), but send assertion failures to the log as well as to
45 #define tor_assert(expr) STMT_BEGIN \
46 if (PREDICT_UNLIKELY(!(expr))) { \
47 log_err(LD_BUG, "%s:%d: %s: Assertion %s failed; aborting.", \
48 _SHORT_FILE_, __LINE__, __func__, #expr); \
49 fprintf(stderr,"%s:%d %s: Assertion %s failed; aborting.\n", \
50 _SHORT_FILE_, __LINE__, __func__, #expr); \
54 /* If we're building with dmalloc, we want all of our memory allocation
55 * functions to take an extra file/line pair of arguments. If not, not.
56 * We define DMALLOC_PARAMS to the extra parameters to insert in the
57 * function prototypes, and DMALLOC_ARGS to the extra arguments to add
60 #define DMALLOC_PARAMS , const char *file, const int line
61 #define DMALLOC_ARGS , _SHORT_FILE_, __LINE__
63 #define DMALLOC_PARAMS
67 /** Define this if you want Tor to crash when any problem comes up,
68 * so you can get a coredump and track things down. */
69 // #define tor_fragile_assert() tor_assert(0)
70 #define tor_fragile_assert()
72 /* Memory management */
73 void *_tor_malloc(size_t size DMALLOC_PARAMS
) ATTR_MALLOC
;
74 void *_tor_malloc_zero(size_t size DMALLOC_PARAMS
) ATTR_MALLOC
;
75 void *_tor_malloc_roundup(size_t *size DMALLOC_PARAMS
) ATTR_MALLOC
;
76 void *_tor_realloc(void *ptr
, size_t size DMALLOC_PARAMS
);
77 char *_tor_strdup(const char *s DMALLOC_PARAMS
) ATTR_MALLOC
ATTR_NONNULL((1));
78 char *_tor_strndup(const char *s
, size_t n DMALLOC_PARAMS
)
79 ATTR_MALLOC
ATTR_NONNULL((1));
80 void *_tor_memdup(const void *mem
, size_t len DMALLOC_PARAMS
)
81 ATTR_MALLOC
ATTR_NONNULL((1));
82 void _tor_free(void *mem
);
84 extern int dmalloc_free(const char *file
, const int line
, void *pnt
,
86 #define tor_free(p) STMT_BEGIN \
87 if (PREDICT_LIKELY((p)!=NULL)) { \
88 dmalloc_free(_SHORT_FILE_, __LINE__, (p), 0); \
93 /** Release memory allocated by tor_malloc, tor_realloc, tor_strdup, etc.
94 * Unlike the free() function, tor_free() will still work on NULL pointers,
95 * and it sets the pointer value to NULL after freeing it.
97 * This is a macro. If you need a function pointer to release memory from
98 * tor_malloc(), use _tor_free().
100 #define tor_free(p) STMT_BEGIN \
101 if (PREDICT_LIKELY((p)!=NULL)) { \
108 #define tor_malloc(size) _tor_malloc(size DMALLOC_ARGS)
109 #define tor_malloc_zero(size) _tor_malloc_zero(size DMALLOC_ARGS)
110 #define tor_malloc_roundup(szp) _tor_malloc_roundup(szp DMALLOC_ARGS)
111 #define tor_realloc(ptr, size) _tor_realloc(ptr, size DMALLOC_ARGS)
112 #define tor_strdup(s) _tor_strdup(s DMALLOC_ARGS)
113 #define tor_strndup(s, n) _tor_strndup(s, n DMALLOC_ARGS)
114 #define tor_memdup(s, n) _tor_memdup(s, n DMALLOC_ARGS)
116 void tor_log_mallinfo(int severity
);
118 /** Return the offset of <b>member</b> within the type <b>tp</b>, in bytes */
119 #if defined(__GNUC__) && __GNUC__ > 3
120 #define STRUCT_OFFSET(tp, member) __builtin_offsetof(tp, member)
122 #define STRUCT_OFFSET(tp, member) \
123 ((off_t) (((char*)&((tp*)0)->member)-(char*)0))
126 /** Macro: yield a pointer to the field at position <b>off</b> within the
127 * structure <b>st</b>. Example:
129 * struct a { int foo; int bar; } x;
130 * off_t bar_offset = STRUCT_OFFSET(struct a, bar);
131 * int *bar_p = STRUCT_VAR_P(&x, bar_offset);
135 #define STRUCT_VAR_P(st, off) ((void*) ( ((char*)(st)) + (off) ) )
137 /** Macro: yield a pointer to an enclosing structure given a pointer to
138 * a substructure at offset <b>off</b>. Example:
140 * struct base { ... };
141 * struct subtype { int x; struct base b; } x;
142 * struct base *bp = &x.base;
143 * struct *sp = SUBTYPE_P(bp, struct subtype, b);
146 #define SUBTYPE_P(p, subtype, basemember) \
147 ((void*) ( ((char*)(p)) - STRUCT_OFFSET(subtype, basemember) ))
150 /** Macro: true if two values have the same boolean value. */
151 #define bool_eq(a,b) (!(a)==!(b))
152 /** Macro: true if two values have different boolean values. */
153 #define bool_neq(a,b) (!(a)!=!(b))
156 double tor_mathlog(double d
) ATTR_CONST
;
157 long tor_lround(double d
) ATTR_CONST
;
158 int tor_log2(uint64_t u64
) ATTR_CONST
;
159 uint64_t round_to_power_of_2(uint64_t u64
);
160 unsigned round_to_next_multiple_of(unsigned number
, unsigned divisor
);
161 uint32_t round_uint32_to_next_multiple_of(uint32_t number
, uint32_t divisor
);
162 uint64_t round_uint64_to_next_multiple_of(uint64_t number
, uint64_t divisor
);
164 /* Compute the CEIL of <b>a</b> divided by <b>b</b>, for nonnegative <b>a</b>
165 * and positive <b>b</b>. Works on integer types only. Not defined if a+b can
167 #define CEIL_DIV(a,b) (((a)+(b)-1)/(b))
169 /* String manipulation */
171 /** Allowable characters in a hexadecimal string. */
172 #define HEX_CHARACTERS "0123456789ABCDEFabcdef"
173 void tor_strlower(char *s
) ATTR_NONNULL((1));
174 void tor_strupper(char *s
) ATTR_NONNULL((1));
175 int tor_strisprint(const char *s
) ATTR_PURE
ATTR_NONNULL((1));
176 int tor_strisnonupper(const char *s
) ATTR_PURE
ATTR_NONNULL((1));
177 int strcmpstart(const char *s1
, const char *s2
) ATTR_PURE
ATTR_NONNULL((1,2));
178 int strcmp_len(const char *s1
, const char *s2
, size_t len
)
179 ATTR_PURE
ATTR_NONNULL((1,2));
180 int strcasecmpstart(const char *s1
, const char *s2
)
181 ATTR_PURE
ATTR_NONNULL((1,2));
182 int strcmpend(const char *s1
, const char *s2
) ATTR_PURE
ATTR_NONNULL((1,2));
183 int strcasecmpend(const char *s1
, const char *s2
)
184 ATTR_PURE
ATTR_NONNULL((1,2));
185 int fast_memcmpstart(const void *mem
, size_t memlen
,
186 const char *prefix
) ATTR_PURE
;
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
) ATTR_PURE
;
199 const char *eat_whitespace_eos(const char *s
, const char *eos
) ATTR_PURE
;
200 const char *eat_whitespace_no_nl(const char *s
) ATTR_PURE
;
201 const char *eat_whitespace_eos_no_nl(const char *s
, const char *eos
) ATTR_PURE
;
202 const char *find_whitespace(const char *s
) ATTR_PURE
;
203 const char *find_whitespace_eos(const char *s
, const char *eos
) ATTR_PURE
;
204 const char *find_str_at_start_of_line(const char *haystack
, const char *needle
)
206 int tor_mem_is_zero(const char *mem
, size_t len
) ATTR_PURE
;
207 int tor_digest_is_zero(const char *digest
) ATTR_PURE
;
208 int tor_digest256_is_zero(const char *digest
) ATTR_PURE
;
209 char *esc_for_log(const char *string
) ATTR_MALLOC
;
210 const char *escaped(const char *string
);
212 void wrap_string(struct smartlist_t
*out
, const char *string
, size_t width
,
213 const char *prefix0
, const char *prefixRest
);
214 int tor_vsscanf(const char *buf
, const char *pattern
, va_list ap
);
215 int tor_sscanf(const char *buf
, const char *pattern
, ...)
217 __attribute__((format(scanf
, 2, 3)))
221 int hex_decode_digit(char c
);
222 void base16_encode(char *dest
, size_t destlen
, const char *src
, size_t srclen
);
223 int base16_decode(char *dest
, size_t destlen
, const char *src
, size_t srclen
);
226 double tv_to_double(const struct timeval
*tv
);
227 int64_t tv_to_msec(const struct timeval
*tv
);
228 int64_t tv_to_usec(const struct timeval
*tv
);
229 long tv_udiff(const struct timeval
*start
, const struct timeval
*end
);
230 long tv_mdiff(const struct timeval
*start
, const struct timeval
*end
);
231 time_t tor_timegm(struct tm
*tm
);
232 #define RFC1123_TIME_LEN 29
233 void format_rfc1123_time(char *buf
, time_t t
);
234 int parse_rfc1123_time(const char *buf
, time_t *t
);
235 #define ISO_TIME_LEN 19
236 void format_local_iso_time(char *buf
, time_t t
);
237 void format_iso_time(char *buf
, time_t t
);
238 int parse_iso_time(const char *buf
, time_t *t
);
239 int parse_http_time(const char *buf
, struct tm
*tm
);
240 int format_time_interval(char *out
, size_t out_len
, long interval
);
244 #define approx_time() time(NULL)
245 #define update_approx_time(t) STMT_NIL
247 time_t approx_time(void);
248 void update_approx_time(time_t now
);
253 /** A ratelim_t remembers how often an event is occurring, and how often
254 * it's allowed to occur. Typical usage is something like:
257 if (possibly_very_frequent_event()) {
258 const int INTERVAL = 300;
259 static ratelim_t warning_limit = RATELIM_INIT(INTERVAL);
261 if ((m = rate_limit_log(&warning_limit, approx_time()))) {
262 log_warn(LD_GENERAL, "The event occurred!%s", m);
268 typedef struct ratelim_t
{
271 int n_calls_since_last_time
;
274 #define RATELIM_INIT(r) { (r), 0, 0 }
276 char *rate_limit_log(ratelim_t
*lim
, time_t now
);
279 ssize_t
write_all(int fd
, const char *buf
, size_t count
, int isSocket
);
280 ssize_t
read_all(int fd
, char *buf
, size_t count
, int isSocket
);
282 /** Return values from file_status(); see that function's documentation
284 typedef enum { FN_ERROR
, FN_NOENT
, FN_FILE
, FN_DIR
} file_status_t
;
285 file_status_t
file_status(const char *filename
);
287 /** Possible behaviors for check_private_dir() on encountering a nonexistent
288 * directory; see that function's documentation for details. */
289 typedef unsigned int cpd_check_t
;
293 #define CPD_GROUP_OK 4
294 #define CPD_CHECK_MODE_ONLY 8
295 int check_private_dir(const char *dirname
, cpd_check_t check
);
296 #define OPEN_FLAGS_REPLACE (O_WRONLY|O_CREAT|O_TRUNC)
297 #define OPEN_FLAGS_APPEND (O_WRONLY|O_CREAT|O_APPEND)
298 typedef struct open_file_t open_file_t
;
299 int start_writing_to_file(const char *fname
, int open_flags
, int mode
,
300 open_file_t
**data_out
);
301 FILE *start_writing_to_stdio_file(const char *fname
, int open_flags
, int mode
,
302 open_file_t
**data_out
);
303 FILE *fdopen_file(open_file_t
*file_data
);
304 int finish_writing_to_file(open_file_t
*file_data
);
305 int abort_writing_to_file(open_file_t
*file_data
);
306 int write_str_to_file(const char *fname
, const char *str
, int bin
);
307 int write_bytes_to_file(const char *fname
, const char *str
, size_t len
,
309 /** An ad-hoc type to hold a string of characters and a count; used by
310 * write_chunks_to_file. */
311 typedef struct sized_chunk_t
{
315 int write_chunks_to_file(const char *fname
, const struct smartlist_t
*chunks
,
317 int append_bytes_to_file(const char *fname
, const char *str
, size_t len
,
320 /** Flag for read_file_to_str: open the file in binary mode. */
322 /** Flag for read_file_to_str: it's okay if the file doesn't exist. */
323 #define RFTS_IGNORE_MISSING 2
326 char *read_file_to_str(const char *filename
, int flags
, struct stat
*stat_out
)
328 const char *parse_config_line_from_str(const char *line
,
329 char **key_out
, char **value_out
);
330 char *expand_filename(const char *filename
);
331 struct smartlist_t
*tor_listdir(const char *dirname
);
332 int path_is_relative(const char *filename
) ATTR_PURE
;
334 /* Process helpers */
335 void start_daemon(void);
336 void finish_daemon(const char *desired_cwd
);
337 void write_pidfile(char *filename
);
340 HANDLE
load_windows_system_library(const TCHAR
*library_name
);
343 const char *libor_get_digests(void);