2 Unix SMB/CIFS implementation.
3 Utility functions for Samba
4 Copyright (C) Andrew Tridgell 1992-1999
5 Copyright (C) Jelmer Vernooij 2005
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 3 of the License, or
10 (at your option) any later version.
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with this program. If not, see <http://www.gnu.org/licenses/>.
21 #ifndef _SAMBA_UTIL_H_
22 #define _SAMBA_UTIL_H_
26 * @brief Helpful macros
32 extern const char *logfile;
34 extern const char *panic_action;
40 #define SMB_ASSERT(b) do { if (!(b)) { \
41 DEBUG(0,("PANIC: assert failed at %s(%d): %s\n", \
42 __FILE__, __LINE__, #b)); smb_panic("assert failed: " #b); }} while(0)
44 /* redefine the assert macro for non-developer builds */
45 #define SMB_ASSERT(b) do { if (!(b)) { \
46 DEBUG(0,("PANIC: assert failed at %s(%d): %s\n", \
47 __FILE__, __LINE__, #b)); }} while (0)
50 #if _SAMBA_BUILD_ == 4
52 #define strlen(x) valgrind_strlen(x)
53 size_t valgrind_strlen(const char *s);
58 #define ABS(a) ((a)>0?(a):(-(a)))
62 * Write backtrace to debug log
64 _PUBLIC_ void call_backtrace(void);
67 Something really nasty happened - panic !
69 _PUBLIC_ _NORETURN_ void smb_panic(const char *why);
72 setup our fault handlers
74 _PUBLIC_ void fault_setup(const char *pname);
77 register a fault handler.
78 Should only be called once in the execution of smbd.
80 _PUBLIC_ bool register_fault_handler(const char *name, void (*fault_handler)(int sig));
82 /* The following definitions come from lib/util/signal.c */
88 void BlockSignals(bool block, int signum);
91 Catch a signal. This should implement the following semantics:
93 1) The handler remains installed after being called.
94 2) The signal should be blocked during handler execution.
96 void (*CatchSignal(int signum,void (*handler)(int )))(int);
99 Ignore SIGCLD via whatever means is necessary for this OS.
101 void CatchChild(void);
104 Catch SIGCLD but leave the child around so it's status can be reaped.
106 void CatchChildLeaveStatus(void);
109 /* The following definitions come from lib/util/util_str.c */
113 Trim the specified elements off the front and back of a string.
115 _PUBLIC_ bool trim_string(char *s, const char *front, const char *back);
118 Find the number of 'c' chars in a string
120 _PUBLIC_ _PURE_ size_t count_chars(const char *s, char c);
123 Safe string copy into a known length string. maxlength does not
124 include the terminating zero.
126 _PUBLIC_ char *safe_strcpy(char *dest,const char *src, size_t maxlength);
129 Safe string cat into a string. maxlength does not
130 include the terminating zero.
132 _PUBLIC_ char *safe_strcat(char *dest, const char *src, size_t maxlength);
135 Routine to get hex characters and turn them into a 16 byte array.
136 the array can be variable length, and any non-hex-numeric
137 characters are skipped. "0xnn" or "0Xnn" is specially catered
140 valid examples: "0A5D15"; "0x15, 0x49, 0xa2"; "59\ta9\te3\n"
144 _PUBLIC_ size_t strhex_to_str(char *p, size_t p_len, const char *strhex, size_t strhex_len);
148 * Parse a hex string and return a data blob.
150 _PUBLIC_ _PURE_ DATA_BLOB strhex_to_data_blob(TALLOC_CTX *mem_ctx, const char *strhex) ;
154 * Routine to print a buffer as HEX digits, into an allocated string.
156 _PUBLIC_ void hex_encode(const unsigned char *buff_in, size_t len, char **out_hex_buffer);
159 * talloc version of hex_encode()
161 _PUBLIC_ char *hex_encode_talloc(TALLOC_CTX *mem_ctx, const unsigned char *buff_in, size_t len);
164 Substitute a string for a pattern in another string. Make sure there is
167 This routine looks for pattern in s and replaces it with
168 insert. It may do multiple replacements.
170 Any of " ; ' $ or ` in the insert string are replaced with _
171 if len==0 then the string cannot be extended. This is different from the old
172 use of len==0 which was for no length checks to be done.
174 _PUBLIC_ void string_sub(char *s,const char *pattern, const char *insert, size_t len);
177 _PUBLIC_ char *string_sub_talloc(TALLOC_CTX *mem_ctx, const char *s,
178 const char *pattern, const char *insert);
181 Similar to string_sub() but allows for any character to be substituted.
183 if len==0 then the string cannot be extended. This is different from the old
184 use of len==0 which was for no length checks to be done.
186 _PUBLIC_ void all_string_sub(char *s,const char *pattern,const char *insert, size_t len);
189 Unescape a URL encoded string, in place.
191 _PUBLIC_ void rfc1738_unescape(char *buf);
194 format a string into length-prefixed dotted domain format, as used in NBT
195 and in some ADS structures
197 _PUBLIC_ const char *str_format_nbt_domain(TALLOC_CTX *mem_ctx, const char *s);
200 * Add a string to an array of strings.
202 * num should be a pointer to an integer that holds the current
203 * number of elements in strings. It will be updated by this function.
205 _PUBLIC_ bool add_string_to_array(TALLOC_CTX *mem_ctx,
206 const char *str, const char ***strings, int *num);
209 varient of strcmp() that handles NULL ptrs
211 _PUBLIC_ int strcmp_safe(const char *s1, const char *s2);
214 return the number of bytes occupied by a buffer in ASCII format
215 the result includes the null termination
218 _PUBLIC_ size_t ascii_len_n(const char *src, size_t n);
221 Set a boolean variable from the text value stored in the passed string.
222 Returns true in success, false if the passed string does not correctly
225 _PUBLIC_ bool set_boolean(const char *boolean_string, bool *boolean);
228 * Parse a string containing a boolean value.
230 * val will be set to the read value.
232 * @retval true if a boolean value was parsed, false otherwise.
234 _PUBLIC_ bool conv_str_bool(const char * str, bool * val);
236 #if _SAMBA_BUILD_ == 4
238 * Convert a size specification like 16K into an integral number of bytes.
240 _PUBLIC_ bool conv_str_size(const char * str, uint64_t * val);
244 * Parse a uint64_t value from a string
246 * val will be set to the value read.
248 * @retval true if parsing was successful, false otherwise
250 _PUBLIC_ bool conv_str_u64(const char * str, uint64_t * val);
253 return the number of bytes occupied by a buffer in CH_UTF16 format
254 the result includes the null termination
256 _PUBLIC_ size_t utf16_len(const void *buf);
259 return the number of bytes occupied by a buffer in CH_UTF16 format
260 the result includes the null termination
263 _PUBLIC_ size_t utf16_len_n(const void *src, size_t n);
264 _PUBLIC_ size_t ucs2_align(const void *base_ptr, const void *p, int flags);
267 Do a case-insensitive, whitespace-ignoring string compare.
269 _PUBLIC_ int strwicmp(const char *psz1, const char *psz2);
274 _PUBLIC_ void string_replace(char *s, char oldc, char newc);
279 * @note The comparison is case-insensitive.
281 _PUBLIC_ bool strequal(const char *s1, const char *s2);
283 /* The following definitions come from lib/util/util_strlist.c */
286 /* separators for lists */
288 #define LIST_SEP " \t,\n\r"
292 build a null terminated list of strings from a input string and a
293 separator list. The separator list must contain characters less than
294 or equal to 0x2f for this to work correctly on multi-byte strings
296 _PUBLIC_ char **str_list_make(TALLOC_CTX *mem_ctx, const char *string, const char *sep);
299 * build a null terminated list of strings from an argv-like input string
300 * Entries are seperated by spaces and can be enclosed by quotes.
301 * Does NOT support escaping
303 _PUBLIC_ const char **str_list_make_shell(TALLOC_CTX *mem_ctx, const char *string, const char *sep);
306 * join a list back to one string
308 _PUBLIC_ char *str_list_join(TALLOC_CTX *mem_ctx, const char **list, char seperator);
310 /** join a list back to one (shell-like) string; entries
311 * seperated by spaces, using quotes where necessary */
312 _PUBLIC_ char *str_list_join_shell(TALLOC_CTX *mem_ctx, const char **list, char sep);
315 return the number of elements in a string list
317 _PUBLIC_ size_t str_list_length(const char * const *list);
322 _PUBLIC_ char **str_list_copy(TALLOC_CTX *mem_ctx, const char **list);
325 Return true if all the elements of the list match exactly.
327 _PUBLIC_ bool str_list_equal(const char **list1, const char **list2);
330 add an entry to a string list
332 _PUBLIC_ const char **str_list_add(const char **list, const char *s);
335 remove an entry from a string list
337 _PUBLIC_ void str_list_remove(const char **list, const char *s);
340 return true if a string is in a list
342 _PUBLIC_ bool str_list_check(const char **list, const char *s);
345 return true if a string is in a list, case insensitively
347 _PUBLIC_ bool str_list_check_ci(const char **list, const char *s);
350 /* The following definitions come from lib/util/util_file.c */
355 read a line from a file with possible \ continuation chars.
356 Blanks at the start or end of a line are stripped.
357 The string will be allocated if s2 is NULL
359 _PUBLIC_ char *fgets_slash(char *s2,int maxlen,XFILE *f);
363 * Read one line (data until next newline or eof) and allocate it
365 _PUBLIC_ char *afdgets(int fd, TALLOC_CTX *mem_ctx, size_t hint);
369 load a file into memory from a fd.
371 _PUBLIC_ char *fd_load(int fd, size_t *size, size_t maxsize, TALLOC_CTX *mem_ctx);
374 char **file_lines_parse(char *p, size_t size, int *numlines, TALLOC_CTX *mem_ctx);
377 load a file into memory
379 _PUBLIC_ char *file_load(const char *fname, size_t *size, size_t maxsize, TALLOC_CTX *mem_ctx);
383 mmap (if possible) or read a file
385 _PUBLIC_ void *map_file(const char *fname, size_t size);
389 load a file into memory and return an array of pointers to lines in the file
390 must be freed with talloc_free().
392 _PUBLIC_ char **file_lines_load(const char *fname, int *numlines, size_t maxsize, TALLOC_CTX *mem_ctx);
396 load a fd into memory and return an array of pointers to lines in the file
397 must be freed with talloc_free(). If convert is true calls unix_to_dos on
400 _PUBLIC_ char **fd_lines_load(int fd, int *numlines, size_t maxsize, TALLOC_CTX *mem_ctx);
403 take a list of lines and modify them to produce a list where \ continues
406 _PUBLIC_ void file_lines_slashcont(char **lines);
409 save a lump of data into a file. Mostly used for debugging
411 _PUBLIC_ bool file_save(const char *fname, const void *packet, size_t length);
412 _PUBLIC_ int vfdprintf(int fd, const char *format, va_list ap) PRINTF_ATTRIBUTE(2,0);
413 _PUBLIC_ int fdprintf(int fd, const char *format, ...) PRINTF_ATTRIBUTE(2,3);
414 _PUBLIC_ bool large_file_support(const char *path);
416 /* The following definitions come from lib/util/util.c */
420 Find a suitable temporary directory. The result should be copied immediately
421 as it may be overwritten by a subsequent call.
423 _PUBLIC_ const char *tmpdir(void);
426 Check if a file exists - call vfs_file_exist for samba files.
428 _PUBLIC_ bool file_exist(const char *fname);
431 Check a files mod time.
433 _PUBLIC_ time_t file_modtime(const char *fname);
436 Check if a directory exists.
438 _PUBLIC_ bool directory_exist(const char *dname);
441 * Try to create the specified directory if it didn't exist.
443 * @retval true if the directory already existed and has the right permissions
444 * or was successfully created.
446 _PUBLIC_ bool directory_create_or_exist(const char *dname, uid_t uid,
450 Set a fd into blocking/nonblocking mode. Uses POSIX O_NONBLOCK if available,
455 _PUBLIC_ int set_blocking(int fd, bool set);
458 Sleep for a specified number of milliseconds.
460 _PUBLIC_ void msleep(unsigned int t);
463 Get my own name, return in malloc'ed storage.
465 _PUBLIC_ char* get_myname(void);
468 Return true if a string could be a pure IP address.
470 _PUBLIC_ bool is_ipaddress(const char *str);
473 Interpret an internet address or name into an IP address in 4 byte form.
475 _PUBLIC_ uint32_t interpret_addr(const char *str);
478 A convenient addition to interpret_addr().
480 _PUBLIC_ struct in_addr interpret_addr2(const char *str);
483 Check if an IP is the 0.0.0.0.
485 _PUBLIC_ bool is_zero_ip_v4(struct in_addr ip);
488 Are two IPs on the same subnet?
490 _PUBLIC_ bool same_net_v4(struct in_addr ip1,struct in_addr ip2,struct in_addr mask);
492 _PUBLIC_ bool is_ipaddress_v4(const char *str);
495 Check if a process exists. Does this work on all unixes?
497 _PUBLIC_ bool process_exists_by_pid(pid_t pid);
500 Simple routine to do POSIX file locking. Cruft in NFS and 64->32 bit mapping
501 is dealt with in posix.c
503 _PUBLIC_ bool fcntl_lock(int fd, int op, off_t offset, off_t count, int type);
506 malloc that aborts with smb_panic on fail or zero size.
508 _PUBLIC_ void *smb_xmalloc(size_t size);
511 Memdup with smb_panic on fail.
513 _PUBLIC_ void *smb_xmemdup(const void *p, size_t size);
516 strdup that aborts on malloc fail.
518 _PUBLIC_ char *smb_xstrdup(const char *s);
520 char *smb_xstrndup(const char *s, size_t n);
523 Like strdup but for memory.
525 _PUBLIC_ void *memdup(const void *p, size_t size);
528 * see if a range of memory is all zero. A NULL pointer is considered
531 _PUBLIC_ bool all_zero(const uint8_t *ptr, size_t size);
534 realloc an array, checking for integer overflow in the array size
536 _PUBLIC_ void *realloc_array(void *ptr, size_t el_size, unsigned count, bool free_on_fail);
538 void *malloc_array(size_t el_size, unsigned int count);
540 /* The following definitions come from lib/util/fsusage.c */
544 * Retrieve amount of free disk space.
545 * this does all of the system specific guff to get the free disk space.
546 * It is derived from code in the GNU fileutils package, but has been
547 * considerably mangled for use here
549 * results are returned in *dfree and *dsize, in 512 byte units
551 _PUBLIC_ int sys_fsusage(const char *path, uint64_t *dfree, uint64_t *dsize);
553 /* The following definitions come from lib/util/ms_fnmatch.c */
558 * @brief MS-style Filename matching
561 #if _SAMBA_BUILD_ == 4
562 /* protocol types. It assumes that higher protocols include lower protocols
563 as subsets. FIXME: Move to one of the smb-specific headers */
564 enum protocol_types {
574 int ms_fnmatch(const char *pattern, const char *string, enum protocol_types protocol);
576 /** a generic fnmatch function - uses for non-CIFS pattern matching */
577 int gen_fnmatch(const char *pattern, const char *string);
580 /* The following definitions come from lib/util/mutex.c */
585 register a set of mutex/rwlock handlers.
586 Should only be called once in the execution of smbd.
588 _PUBLIC_ bool register_mutex_handlers(const char *name, struct mutex_ops *ops);
591 /* The following definitions come from lib/util/idtree.c */
595 initialise a idr tree. The context return value must be passed to
596 all subsequent idr calls. To destroy the idr tree use talloc_free()
599 _PUBLIC_ struct idr_context *idr_init(TALLOC_CTX *mem_ctx);
602 allocate the next available id, and assign 'ptr' into its slot.
603 you can retrieve later this pointer using idr_find()
605 _PUBLIC_ int idr_get_new(struct idr_context *idp, void *ptr, int limit);
608 allocate a new id, giving the first available value greater than or
609 equal to the given starting id
611 _PUBLIC_ int idr_get_new_above(struct idr_context *idp, void *ptr, int starting_id, int limit);
614 allocate a new id randomly in the given range
616 _PUBLIC_ int idr_get_new_random(struct idr_context *idp, void *ptr, int limit);
619 find a pointer value previously set with idr_get_new given an id
621 _PUBLIC_ void *idr_find(struct idr_context *idp, int id);
624 remove an id from the idr tree
626 _PUBLIC_ int idr_remove(struct idr_context *idp, int id);
628 /* The following definitions come from lib/util/become_daemon.c */
630 #if _SAMBA_BUILD_ == 4
632 Become a daemon, discarding the controlling terminal.
634 _PUBLIC_ void become_daemon(bool fork);
638 * Load a ini-style file.
640 bool pm_process( const char *fileName,
641 bool (*sfunc)(const char *, void *),
642 bool (*pfunc)(const char *, const char *, void *),
646 * Add-on to talloc_get_type
648 _PUBLIC_ void *talloc_check_name_abort(const void *ptr, const char *name);
649 #define talloc_get_type_abort(ptr, type) \
650 (type *)talloc_check_name_abort(ptr, #type)
652 bool unmap_file(void *start, size_t size);
654 #define CONST_DISCARD(type, ptr) ((type) ((void *) (ptr)))
656 #endif /* _SAMBA_UTIL_H_ */