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_
24 #include "lib/util/charset/charset.h"
25 #include "lib/util/attr.h"
32 * @brief Helpful macros
37 extern const char *logfile;
38 extern const char *panic_action;
40 #include "lib/util/time.h"
41 #include "lib/util/data_blob.h"
42 #include "lib/util/xfile.h"
43 #include "lib/util/byteorder.h"
44 #include "lib/util/talloc_stack.h"
50 #define SMB_ASSERT(b) do { if (!(b)) { \
51 DEBUG(0,("PANIC: assert failed at %s(%d): %s\n", \
52 __FILE__, __LINE__, #b)); smb_panic("assert failed: " #b); }} while(0)
54 /* redefine the assert macro for non-developer builds */
55 #define SMB_ASSERT(b) do { if (!(b)) { \
56 DEBUG(0,("PANIC: assert failed at %s(%d): %s\n", \
57 __FILE__, __LINE__, #b)); }} while (0)
61 #define ABS(a) ((a)>0?(a):(-(a)))
64 #include "lib/util/memory.h"
67 * Write backtrace to debug log
69 _PUBLIC_ void call_backtrace(void);
72 Something really nasty happened - panic !
74 typedef void (*smb_panic_handler_t)(const char *why);
76 _PUBLIC_ void fault_configure(smb_panic_handler_t panic_handler);
77 _PUBLIC_ void fault_setup(void);
78 _PUBLIC_ void fault_setup_disable(void);
79 _PUBLIC_ void dump_core_setup(const char *progname, const char *logfile);
80 _PUBLIC_ void smb_panic(const char *reason);
84 register a fault handler.
85 Should only be called once in the execution of smbd.
87 _PUBLIC_ bool register_fault_handler(const char *name, void (*fault_handler)(int sig));
89 /* The following definitions come from lib/util/signal.c */
95 void BlockSignals(bool block, int signum);
98 Catch a signal. This should implement the following semantics:
100 1) The handler remains installed after being called.
101 2) The signal should be blocked during handler execution.
103 void (*CatchSignal(int signum,void (*handler)(int )))(int);
106 Ignore SIGCLD via whatever means is necessary for this OS.
108 void CatchChild(void);
111 Catch SIGCLD but leave the child around so it's status can be reaped.
113 void CatchChildLeaveStatus(void);
115 /* The following definitions come from lib/util/system.c */
117 /**************************************************************************
118 A wrapper for gethostbyname() that tries avoids looking up hostnames
119 in the root domain, which can cause dial-on-demand links to come up for no
121 ****************************************************************************/
122 _PUBLIC_ struct hostent *sys_gethostbyname(const char *name);
123 _PUBLIC_ struct in_addr sys_inet_makeaddr(int net, int host);
126 * Wrapper for fork used to invalid pid cache.
128 _PUBLIC_ pid_t sys_fork(void);
131 * Wrapper for getpid. Ensures we only do a system call *once*.
133 _PUBLIC_ pid_t sys_getpid(void);
135 /* The following definitions come from lib/util/genrand.c */
138 Copy any user given reseed data.
140 _PUBLIC_ void set_rand_reseed_callback(void (*fn)(void *, int *), void *);
143 * Tell the random number generator it needs to reseed.
145 _PUBLIC_ void set_need_random_reseed(void);
148 Interface to the (hopefully) good crypto random number generator.
149 Will use our internal PRNG if more than 40 bytes of random generation
150 has been requested, otherwise tries to read from /dev/random
152 _PUBLIC_ void generate_random_buffer(uint8_t *out, int len);
155 Interface to the (hopefully) good crypto random number generator.
156 Will always use /dev/urandom if available.
158 _PUBLIC_ void generate_secret_buffer(uint8_t *out, int len);
161 generate a single random uint32_t
163 _PUBLIC_ uint32_t generate_random(void);
166 very basic password quality checker
168 _PUBLIC_ bool check_password_quality(const char *s);
171 * Generate a random text password.
173 _PUBLIC_ char *generate_random_password(TALLOC_CTX *mem_ctx, size_t min, size_t max);
176 Use the random number generator to generate a random string.
178 _PUBLIC_ char *generate_random_str_list(TALLOC_CTX *mem_ctx, size_t len, const char *list);
181 * Generate a random text string consisting of the specified length.
182 * The returned string will be allocated.
184 * Characters used are: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+_-#.,
186 _PUBLIC_ char *generate_random_str(TALLOC_CTX *mem_ctx, size_t len);
189 * Generate an array of unique text strings all of the same length.
190 * The returned strings will be allocated.
191 * Returns NULL if the number of unique combinations cannot be created.
193 * Characters used are: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+_-#.,
195 _PUBLIC_ char** generate_unique_strs(TALLOC_CTX *mem_ctx, size_t len,
198 /* The following definitions come from lib/util/dprintf.c */
199 #if _SAMBA_BUILD_ == 4
201 _PUBLIC_ void d_set_iconv(smb_iconv_t);
202 _PUBLIC_ int d_vfprintf(FILE *f, const char *format, va_list ap) PRINTF_ATTRIBUTE(2,0);
203 _PUBLIC_ int d_fprintf(FILE *f, const char *format, ...) PRINTF_ATTRIBUTE(2,3);
204 _PUBLIC_ int d_printf(const char *format, ...) PRINTF_ATTRIBUTE(1,2);
205 _PUBLIC_ void display_set_stderr(void);
208 /* The following definitions come from lib/util/util_str.c */
210 bool next_token_talloc(TALLOC_CTX *ctx,
216 * Get the next token from a string, return false if none found. Handles
217 * double-quotes. This version does not trim leading separator characters
218 * before looking for a token.
220 bool next_token_no_ltrim_talloc(TALLOC_CTX *ctx,
227 Trim the specified elements off the front and back of a string.
229 _PUBLIC_ bool trim_string(char *s, const char *front, const char *back);
232 Find the number of 'c' chars in a string
234 _PUBLIC_ _PURE_ size_t count_chars(const char *s, char c);
237 Safe string copy into a known length string. maxlength does not
238 include the terminating zero.
240 _PUBLIC_ char *safe_strcpy(char *dest,const char *src, size_t maxlength);
243 Safe string cat into a string. maxlength does not
244 include the terminating zero.
246 _PUBLIC_ char *safe_strcat(char *dest, const char *src, size_t maxlength);
249 Routine to get hex characters and turn them into a 16 byte array.
250 the array can be variable length, and any non-hex-numeric
251 characters are skipped. "0xnn" or "0Xnn" is specially catered
254 valid examples: "0A5D15"; "0x15, 0x49, 0xa2"; "59\ta9\te3\n"
258 _PUBLIC_ size_t strhex_to_str(char *p, size_t p_len, const char *strhex, size_t strhex_len);
261 * Parse a hex string and return a data blob.
263 _PUBLIC_ _PURE_ DATA_BLOB strhex_to_data_blob(TALLOC_CTX *mem_ctx, const char *strhex) ;
266 * Routine to print a buffer as HEX digits, into an allocated string.
268 _PUBLIC_ void hex_encode(const unsigned char *buff_in, size_t len, char **out_hex_buffer);
271 * talloc version of hex_encode()
273 _PUBLIC_ char *hex_encode_talloc(TALLOC_CTX *mem_ctx, const unsigned char *buff_in, size_t len);
276 Substitute a string for a pattern in another string. Make sure there is
279 This routine looks for pattern in s and replaces it with
280 insert. It may do multiple replacements.
282 Any of " ; ' $ or ` in the insert string are replaced with _
283 if len==0 then the string cannot be extended. This is different from the old
284 use of len==0 which was for no length checks to be done.
286 _PUBLIC_ void string_sub(char *s,const char *pattern, const char *insert, size_t len);
289 _PUBLIC_ char *string_sub_talloc(TALLOC_CTX *mem_ctx, const char *s,
290 const char *pattern, const char *insert);
293 Similar to string_sub() but allows for any character to be substituted.
295 if len==0 then the string cannot be extended. This is different from the old
296 use of len==0 which was for no length checks to be done.
298 _PUBLIC_ void all_string_sub(char *s,const char *pattern,const char *insert, size_t len);
301 Unescape a URL encoded string, in place.
303 _PUBLIC_ void rfc1738_unescape(char *buf);
308 * Returns a static buffer that contains the RFC
309 * 1738 compliant, escaped version of the given url. (escapes unsafe and % characters)
311 _PUBLIC_ char *rfc1738_escape(TALLOC_CTX *mem_ctx, const char *url);
314 * rfc1738_escape_unescaped
316 * Returns a static buffer that contains
317 * the RFC 1738 compliant, escaped version of the given url (escapes unsafe chars only)
319 _PUBLIC_ char *rfc1738_escape_unescaped(TALLOC_CTX *mem_ctx, const char *url);
322 * rfc1738_escape_part
323 * Returns a static buffer that contains the RFC
324 * 1738 compliant, escaped version of the given url segment. (escapes
325 * unsafe, reserved and % chars) It would mangle the :// in http://,
326 * and mangle paths (because of /).
328 _PUBLIC_ char *rfc1738_escape_part(TALLOC_CTX *mem_ctx, const char *url);
331 format a string into length-prefixed dotted domain format, as used in NBT
332 and in some ADS structures
334 _PUBLIC_ const char *str_format_nbt_domain(TALLOC_CTX *mem_ctx, const char *s);
337 * Add a string to an array of strings.
339 * num should be a pointer to an integer that holds the current
340 * number of elements in strings. It will be updated by this function.
342 _PUBLIC_ bool add_string_to_array(TALLOC_CTX *mem_ctx,
343 const char *str, const char ***strings, int *num);
346 varient of strcmp() that handles NULL ptrs
348 _PUBLIC_ int strcmp_safe(const char *s1, const char *s2);
351 return the number of bytes occupied by a buffer in ASCII format
352 the result includes the null termination
355 _PUBLIC_ size_t ascii_len_n(const char *src, size_t n);
358 Set a boolean variable from the text value stored in the passed string.
359 Returns true in success, false if the passed string does not correctly
362 _PUBLIC_ bool set_boolean(const char *boolean_string, bool *boolean);
365 * Parse a string containing a boolean value.
367 * val will be set to the read value.
369 * @retval true if a boolean value was parsed, false otherwise.
371 _PUBLIC_ bool conv_str_bool(const char * str, bool * val);
373 #if _SAMBA_BUILD_ == 4
375 * Convert a size specification like 16K into an integral number of bytes.
377 _PUBLIC_ bool conv_str_size(const char * str, uint64_t * val);
381 * Parse a uint64_t value from a string
383 * val will be set to the value read.
385 * @retval true if parsing was successful, false otherwise
387 _PUBLIC_ bool conv_str_u64(const char * str, uint64_t * val);
390 return the number of bytes occupied by a buffer in CH_UTF16 format
391 the result includes the null termination
393 _PUBLIC_ size_t utf16_len(const void *buf);
396 return the number of bytes occupied by a buffer in CH_UTF16 format
397 the result includes the null termination
400 _PUBLIC_ size_t utf16_len_n(const void *src, size_t n);
401 _PUBLIC_ size_t ucs2_align(const void *base_ptr, const void *p, int flags);
404 Do a case-insensitive, whitespace-ignoring string compare.
406 _PUBLIC_ int strwicmp(const char *psz1, const char *psz2);
411 _PUBLIC_ void string_replace(char *s, char oldc, char newc);
416 * @note The comparison is case-insensitive.
418 _PUBLIC_ bool strequal(const char *s1, const char *s2);
420 /* The following definitions come from lib/util/util_strlist.c */
422 /* separators for lists */
424 #define LIST_SEP " \t,\n\r"
428 build an empty (only NULL terminated) list of strings (for expansion with str_list_add() etc)
430 _PUBLIC_ char **str_list_make_empty(TALLOC_CTX *mem_ctx);
433 place the only element 'entry' into a new, NULL terminated string list
435 _PUBLIC_ char **str_list_make_single(TALLOC_CTX *mem_ctx,
439 build a null terminated list of strings from a input string and a
440 separator list. The separator list must contain characters less than
441 or equal to 0x2f for this to work correctly on multi-byte strings
443 _PUBLIC_ char **str_list_make(TALLOC_CTX *mem_ctx, const char *string,
447 * build a null terminated list of strings from an argv-like input string
448 * Entries are separated by spaces and can be enclosed by quotes.
449 * Does NOT support escaping
451 _PUBLIC_ char **str_list_make_shell(TALLOC_CTX *mem_ctx, const char *string, const char *sep);
454 * join a list back to one string
456 _PUBLIC_ char *str_list_join(TALLOC_CTX *mem_ctx, const char **list, char separator);
458 /** join a list back to one (shell-like) string; entries
459 * separated by spaces, using quotes where necessary */
460 _PUBLIC_ char *str_list_join_shell(TALLOC_CTX *mem_ctx, const char **list, char sep);
463 return the number of elements in a string list
465 _PUBLIC_ size_t str_list_length(const char * const *list);
470 _PUBLIC_ char **str_list_copy(TALLOC_CTX *mem_ctx, const char **list);
473 Return true if all the elements of the list match exactly.
475 _PUBLIC_ bool str_list_equal(const char * const *list1, const char * const *list2);
478 add an entry to a string list
480 _PUBLIC_ const char **str_list_add(const char **list, const char *s);
483 remove an entry from a string list
485 _PUBLIC_ void str_list_remove(const char **list, const char *s);
488 return true if a string is in a list
490 _PUBLIC_ bool str_list_check(const char **list, const char *s);
493 return true if a string is in a list, case insensitively
495 _PUBLIC_ bool str_list_check_ci(const char **list, const char *s);
497 append one list to another - expanding list1
499 _PUBLIC_ const char **str_list_append(const char **list1,
500 const char * const *list2);
503 remove duplicate elements from a list
505 _PUBLIC_ const char **str_list_unique(const char **list);
508 very useful when debugging complex list related code
510 _PUBLIC_ void str_list_show(const char **list);
514 append one list to another - expanding list1
515 this assumes the elements of list2 are const pointers, so we can re-use them
517 _PUBLIC_ const char **str_list_append_const(const char **list1,
521 add an entry to a string list
522 this assumes s will not change
524 _PUBLIC_ const char **str_list_add_const(const char **list, const char *s);
528 this assumes list will not change
530 _PUBLIC_ const char **str_list_copy_const(TALLOC_CTX *mem_ctx,
534 * Needed for making an "unconst" list "const"
536 _PUBLIC_ const char **const_str_list(char **list);
539 /* The following definitions come from lib/util/util_file.c */
543 read a line from a file with possible \ continuation chars.
544 Blanks at the start or end of a line are stripped.
545 The string will be allocated if s2 is NULL
547 _PUBLIC_ char *fgets_slash(char *s2,int maxlen,XFILE *f);
550 * Read one line (data until next newline or eof) and allocate it
552 _PUBLIC_ char *afdgets(int fd, TALLOC_CTX *mem_ctx, size_t hint);
555 load a file into memory from a fd.
557 _PUBLIC_ char *fd_load(int fd, size_t *size, size_t maxsize, TALLOC_CTX *mem_ctx);
560 char **file_lines_parse(char *p, size_t size, int *numlines, TALLOC_CTX *mem_ctx);
563 load a file into memory
565 _PUBLIC_ char *file_load(const char *fname, size_t *size, size_t maxsize, TALLOC_CTX *mem_ctx);
568 mmap (if possible) or read a file
570 _PUBLIC_ void *map_file(const char *fname, size_t size);
573 load a file into memory and return an array of pointers to lines in the file
574 must be freed with talloc_free().
576 _PUBLIC_ char **file_lines_load(const char *fname, int *numlines, size_t maxsize, TALLOC_CTX *mem_ctx);
579 load a fd into memory and return an array of pointers to lines in the file
580 must be freed with talloc_free(). If convert is true calls unix_to_dos on
583 _PUBLIC_ char **fd_lines_load(int fd, int *numlines, size_t maxsize, TALLOC_CTX *mem_ctx);
586 take a list of lines and modify them to produce a list where \ continues
589 _PUBLIC_ void file_lines_slashcont(char **lines);
592 save a lump of data into a file. Mostly used for debugging
594 _PUBLIC_ bool file_save(const char *fname, const void *packet, size_t length);
595 _PUBLIC_ int vfdprintf(int fd, const char *format, va_list ap) PRINTF_ATTRIBUTE(2,0);
596 _PUBLIC_ int fdprintf(int fd, const char *format, ...) PRINTF_ATTRIBUTE(2,3);
597 _PUBLIC_ bool large_file_support(const char *path);
600 compare two files, return true if the two files have the same content
602 bool file_compare(const char *path1, const char *path2);
604 /* The following definitions come from lib/util/util.c */
608 Find a suitable temporary directory. The result should be copied immediately
609 as it may be overwritten by a subsequent call.
611 _PUBLIC_ const char *tmpdir(void);
614 Check if a file exists - call vfs_file_exist for samba files.
616 _PUBLIC_ bool file_exist(const char *fname);
619 Check a files mod time.
621 _PUBLIC_ time_t file_modtime(const char *fname);
624 Check if a directory exists.
626 _PUBLIC_ bool directory_exist(const char *dname);
629 * Try to create the specified directory if it didn't exist.
631 * @retval true if the directory already existed and has the right permissions
632 * or was successfully created.
634 _PUBLIC_ bool directory_create_or_exist(const char *dname, uid_t uid,
638 Set a fd into blocking/nonblocking mode. Uses POSIX O_NONBLOCK if available,
643 _PUBLIC_ int set_blocking(int fd, bool set);
646 Sleep for a specified number of milliseconds.
648 _PUBLIC_ void smb_msleep(unsigned int t);
651 Get my own name, return in talloc'ed storage.
653 _PUBLIC_ char* get_myname(TALLOC_CTX *mem_ctx);
656 Check if a process exists. Does this work on all unixes?
658 _PUBLIC_ bool process_exists_by_pid(pid_t pid);
661 Simple routine to do POSIX file locking. Cruft in NFS and 64->32 bit mapping
662 is dealt with in posix.c
664 _PUBLIC_ bool fcntl_lock(int fd, int op, off_t offset, off_t count, int type);
667 * Write dump of binary data to a callback
669 void dump_data_cb(const uint8_t *buf, int len,
670 bool omit_zero_bytes,
671 void (*cb)(const char *buf, void *private_data),
675 * Write dump of binary data to the log file.
677 * The data is only written if the log level is at least level.
679 _PUBLIC_ void dump_data(int level, const uint8_t *buf,int len);
682 * Write dump of binary data to the log file.
684 * The data is only written if the log level is at least level.
685 * 16 zero bytes in a row are omitted
687 _PUBLIC_ void dump_data_skip_zeros(int level, const uint8_t *buf, int len);
690 malloc that aborts with smb_panic on fail or zero size.
692 _PUBLIC_ void *smb_xmalloc(size_t size);
695 Memdup with smb_panic on fail.
697 _PUBLIC_ void *smb_xmemdup(const void *p, size_t size);
700 strdup that aborts on malloc fail.
702 _PUBLIC_ char *smb_xstrdup(const char *s);
704 char *smb_xstrndup(const char *s, size_t n);
707 Like strdup but for memory.
709 _PUBLIC_ void *memdup(const void *p, size_t size);
712 * Write a password to the log file.
714 * @note Only actually does something if DEBUG_PASSWORD was defined during
717 _PUBLIC_ void dump_data_pw(const char *msg, const uint8_t * data, size_t len);
720 * see if a range of memory is all zero. A NULL pointer is considered
723 _PUBLIC_ bool all_zero(const uint8_t *ptr, size_t size);
726 realloc an array, checking for integer overflow in the array size
728 _PUBLIC_ void *realloc_array(void *ptr, size_t el_size, unsigned count, bool free_on_fail);
730 void *malloc_array(size_t el_size, unsigned int count);
732 /* The following definitions come from lib/util/fsusage.c */
736 * Retrieve amount of free disk space.
737 * this does all of the system specific guff to get the free disk space.
738 * It is derived from code in the GNU fileutils package, but has been
739 * considerably mangled for use here
741 * results are returned in *dfree and *dsize, in 512 byte units
743 _PUBLIC_ int sys_fsusage(const char *path, uint64_t *dfree, uint64_t *dsize);
745 /* The following definitions come from lib/util/ms_fnmatch.c */
750 * @brief MS-style Filename matching
753 #if _SAMBA_BUILD_ == 4
754 /* protocol types. It assumes that higher protocols include lower protocols
755 as subsets. FIXME: Move to one of the smb-specific headers */
756 enum protocol_types {
766 int ms_fnmatch(const char *pattern, const char *string, enum protocol_types protocol);
768 /** a generic fnmatch function - uses for non-CIFS pattern matching */
769 int gen_fnmatch(const char *pattern, const char *string);
772 /* The following definitions come from lib/util/idtree.c */
776 initialise a idr tree. The context return value must be passed to
777 all subsequent idr calls. To destroy the idr tree use talloc_free()
780 _PUBLIC_ struct idr_context *idr_init(TALLOC_CTX *mem_ctx);
783 allocate the next available id, and assign 'ptr' into its slot.
784 you can retrieve later this pointer using idr_find()
786 _PUBLIC_ int idr_get_new(struct idr_context *idp, void *ptr, int limit);
789 allocate a new id, giving the first available value greater than or
790 equal to the given starting id
792 _PUBLIC_ int idr_get_new_above(struct idr_context *idp, void *ptr, int starting_id, int limit);
795 allocate a new id randomly in the given range
797 _PUBLIC_ int idr_get_new_random(struct idr_context *idp, void *ptr, int limit);
800 find a pointer value previously set with idr_get_new given an id
802 _PUBLIC_ void *idr_find(struct idr_context *idp, int id);
805 remove an id from the idr tree
807 _PUBLIC_ int idr_remove(struct idr_context *idp, int id);
809 /* The following definitions come from lib/util/become_daemon.c */
812 Close the low 3 fd's and open dev/null in their place
814 _PUBLIC_ void close_low_fds(bool stderr_too);
817 Become a daemon, discarding the controlling terminal.
819 _PUBLIC_ void become_daemon(bool do_fork, bool no_process_group, bool log_stdout);
822 * Load a ini-style file.
824 bool pm_process( const char *fileName,
825 bool (*sfunc)(const char *, void *),
826 bool (*pfunc)(const char *, const char *, void *),
829 bool unmap_file(void *start, size_t size);
831 void print_asc(int level, const uint8_t *buf,int len);
832 void print_asc_cb(const uint8_t *buf, int len,
833 void (*cb)(const char *buf, void *private_data),
837 * Add an id to an array of ids.
839 * num should be a pointer to an integer that holds the current
840 * number of elements in ids. It will be updated by this function.
843 bool add_uid_to_array_unique(TALLOC_CTX *mem_ctx, uid_t uid,
844 uid_t **uids, uint32_t *num_uids);
845 bool add_gid_to_array_unique(TALLOC_CTX *mem_ctx, gid_t gid,
846 gid_t **gids, uint32_t *num_gids);
849 * Allocate anonymous shared memory of the given size
851 void *anonymous_shared_allocate(size_t bufsz);
852 void anonymous_shared_free(void *ptr);
855 run a command as a child process, with a timeout.
857 any stdout/stderr from the child will appear in the Samba logs with
858 the specified log levels
860 If callback is set then the callback is called on completion
861 with the return code from the command
863 struct tevent_context;
865 struct tevent_req *samba_runcmd_send(TALLOC_CTX *mem_ctx,
866 struct tevent_context *ev,
867 struct timeval endtime,
868 int stdout_log_level,
869 int stderr_log_level,
870 const char * const *argv0, ...);
871 int samba_runcmd_recv(struct tevent_req *req, int *perrno);
874 void samba_start_debugger(void);
877 #endif /* _SAMBA_UTIL_H_ */