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 *panic_action;
39 #include "lib/util/time.h"
40 #include "lib/util/data_blob.h"
41 #include "lib/util/xfile.h"
42 #include "lib/util/byteorder.h"
43 #include "lib/util/talloc_stack.h"
49 #define SMB_ASSERT(b) do { if (!(b)) { \
50 DEBUG(0,("PANIC: assert failed at %s(%d): %s\n", \
51 __FILE__, __LINE__, #b)); smb_panic("assert failed: " #b); }} while(0)
53 /* redefine the assert macro for non-developer builds */
54 #define SMB_ASSERT(b) do { if (!(b)) { \
55 DEBUG(0,("PANIC: assert failed at %s(%d): %s\n", \
56 __FILE__, __LINE__, #b)); }} while (0)
60 #define ABS(a) ((a)>0?(a):(-(a)))
63 #include "lib/util/memory.h"
66 * Write backtrace to debug log
68 _PUBLIC_ void call_backtrace(void);
71 Something really nasty happened - panic !
73 typedef void (*smb_panic_handler_t)(const char *why);
75 _PUBLIC_ void fault_configure(smb_panic_handler_t panic_handler);
76 _PUBLIC_ void fault_setup(void);
77 _PUBLIC_ void fault_setup_disable(void);
78 _PUBLIC_ void dump_core_setup(const char *progname, const char *logfile);
79 _PUBLIC_ void smb_panic(const char *reason);
83 register a fault handler.
84 Should only be called once in the execution of smbd.
86 _PUBLIC_ bool register_fault_handler(const char *name, void (*fault_handler)(int sig));
88 /* The following definitions come from lib/util/signal.c */
94 void BlockSignals(bool block, int signum);
97 Catch a signal. This should implement the following semantics:
99 1) The handler remains installed after being called.
100 2) The signal should be blocked during handler execution.
102 void (*CatchSignal(int signum,void (*handler)(int )))(int);
105 Ignore SIGCLD via whatever means is necessary for this OS.
107 void CatchChild(void);
110 Catch SIGCLD but leave the child around so it's status can be reaped.
112 void CatchChildLeaveStatus(void);
114 /* The following definitions come from lib/util/system.c */
116 /**************************************************************************
117 A wrapper for gethostbyname() that tries avoids looking up hostnames
118 in the root domain, which can cause dial-on-demand links to come up for no
120 ****************************************************************************/
121 _PUBLIC_ struct hostent *sys_gethostbyname(const char *name);
122 _PUBLIC_ struct in_addr sys_inet_makeaddr(int net, int host);
125 * Wrapper for fork used to invalid pid cache.
127 _PUBLIC_ pid_t sys_fork(void);
130 * Wrapper for getpid. Ensures we only do a system call *once*.
132 _PUBLIC_ pid_t sys_getpid(void);
134 /* The following definitions come from lib/util/genrand.c */
137 Copy any user given reseed data.
139 _PUBLIC_ void set_rand_reseed_callback(void (*fn)(void *, int *), void *);
142 * Tell the random number generator it needs to reseed.
144 _PUBLIC_ void set_need_random_reseed(void);
147 Interface to the (hopefully) good crypto random number generator.
148 Will use our internal PRNG if more than 40 bytes of random generation
149 has been requested, otherwise tries to read from /dev/random
151 _PUBLIC_ void generate_random_buffer(uint8_t *out, int len);
154 Interface to the (hopefully) good crypto random number generator.
155 Will always use /dev/urandom if available.
157 _PUBLIC_ void generate_secret_buffer(uint8_t *out, int len);
160 generate a single random uint32_t
162 _PUBLIC_ uint32_t generate_random(void);
165 very basic password quality checker
167 _PUBLIC_ bool check_password_quality(const char *s);
170 * Generate a random text password.
172 _PUBLIC_ char *generate_random_password(TALLOC_CTX *mem_ctx, size_t min, size_t max);
175 Use the random number generator to generate a random string.
177 _PUBLIC_ char *generate_random_str_list(TALLOC_CTX *mem_ctx, size_t len, const char *list);
180 * Generate a random text string consisting of the specified length.
181 * The returned string will be allocated.
183 * Characters used are: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+_-#.,
185 _PUBLIC_ char *generate_random_str(TALLOC_CTX *mem_ctx, size_t len);
188 * Generate an array of unique text strings all of the same length.
189 * The returned strings will be allocated.
190 * Returns NULL if the number of unique combinations cannot be created.
192 * Characters used are: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+_-#.,
194 _PUBLIC_ char** generate_unique_strs(TALLOC_CTX *mem_ctx, size_t len,
197 /* The following definitions come from lib/util/dprintf.c */
198 #if _SAMBA_BUILD_ == 4
200 _PUBLIC_ void d_set_iconv(smb_iconv_t);
201 _PUBLIC_ int d_vfprintf(FILE *f, const char *format, va_list ap) PRINTF_ATTRIBUTE(2,0);
202 _PUBLIC_ int d_fprintf(FILE *f, const char *format, ...) PRINTF_ATTRIBUTE(2,3);
203 _PUBLIC_ int d_printf(const char *format, ...) PRINTF_ATTRIBUTE(1,2);
204 _PUBLIC_ void display_set_stderr(void);
207 /* The following definitions come from lib/util/util_str.c */
209 bool next_token_talloc(TALLOC_CTX *ctx,
215 * Get the next token from a string, return false if none found. Handles
216 * double-quotes. This version does not trim leading separator characters
217 * before looking for a token.
219 bool next_token_no_ltrim_talloc(TALLOC_CTX *ctx,
226 Trim the specified elements off the front and back of a string.
228 _PUBLIC_ bool trim_string(char *s, const char *front, const char *back);
231 Find the number of 'c' chars in a string
233 _PUBLIC_ _PURE_ size_t count_chars(const char *s, char c);
236 Safe string copy into a known length string. maxlength does not
237 include the terminating zero.
239 _PUBLIC_ char *safe_strcpy(char *dest,const char *src, size_t maxlength);
242 Safe string cat into a string. maxlength does not
243 include the terminating zero.
245 _PUBLIC_ char *safe_strcat(char *dest, const char *src, size_t maxlength);
248 Routine to get hex characters and turn them into a 16 byte array.
249 the array can be variable length, and any non-hex-numeric
250 characters are skipped. "0xnn" or "0Xnn" is specially catered
253 valid examples: "0A5D15"; "0x15, 0x49, 0xa2"; "59\ta9\te3\n"
257 _PUBLIC_ size_t strhex_to_str(char *p, size_t p_len, const char *strhex, size_t strhex_len);
260 * Parse a hex string and return a data blob.
262 _PUBLIC_ _PURE_ DATA_BLOB strhex_to_data_blob(TALLOC_CTX *mem_ctx, const char *strhex) ;
265 * Routine to print a buffer as HEX digits, into an allocated string.
267 _PUBLIC_ void hex_encode(const unsigned char *buff_in, size_t len, char **out_hex_buffer);
270 * talloc version of hex_encode()
272 _PUBLIC_ char *hex_encode_talloc(TALLOC_CTX *mem_ctx, const unsigned char *buff_in, size_t len);
275 Substitute a string for a pattern in another string. Make sure there is
278 This routine looks for pattern in s and replaces it with
279 insert. It may do multiple replacements.
281 Any of " ; ' $ or ` in the insert string are replaced with _
282 if len==0 then the string cannot be extended. This is different from the old
283 use of len==0 which was for no length checks to be done.
285 _PUBLIC_ void string_sub(char *s,const char *pattern, const char *insert, size_t len);
288 _PUBLIC_ char *string_sub_talloc(TALLOC_CTX *mem_ctx, const char *s,
289 const char *pattern, const char *insert);
292 Similar to string_sub() but allows for any character to be substituted.
294 if len==0 then the string cannot be extended. This is different from the old
295 use of len==0 which was for no length checks to be done.
297 _PUBLIC_ void all_string_sub(char *s,const char *pattern,const char *insert, size_t len);
300 Unescape a URL encoded string, in place.
302 _PUBLIC_ void rfc1738_unescape(char *buf);
307 * Returns a static buffer that contains the RFC
308 * 1738 compliant, escaped version of the given url. (escapes unsafe and % characters)
310 _PUBLIC_ char *rfc1738_escape(TALLOC_CTX *mem_ctx, const char *url);
313 * rfc1738_escape_unescaped
315 * Returns a static buffer that contains
316 * the RFC 1738 compliant, escaped version of the given url (escapes unsafe chars only)
318 _PUBLIC_ char *rfc1738_escape_unescaped(TALLOC_CTX *mem_ctx, const char *url);
321 * rfc1738_escape_part
322 * Returns a static buffer that contains the RFC
323 * 1738 compliant, escaped version of the given url segment. (escapes
324 * unsafe, reserved and % chars) It would mangle the :// in http://,
325 * and mangle paths (because of /).
327 _PUBLIC_ char *rfc1738_escape_part(TALLOC_CTX *mem_ctx, const char *url);
330 format a string into length-prefixed dotted domain format, as used in NBT
331 and in some ADS structures
333 _PUBLIC_ const char *str_format_nbt_domain(TALLOC_CTX *mem_ctx, const char *s);
336 * Add a string to an array of strings.
338 * num should be a pointer to an integer that holds the current
339 * number of elements in strings. It will be updated by this function.
341 _PUBLIC_ bool add_string_to_array(TALLOC_CTX *mem_ctx,
342 const char *str, const char ***strings, int *num);
345 varient of strcmp() that handles NULL ptrs
347 _PUBLIC_ int strcmp_safe(const char *s1, const char *s2);
350 return the number of bytes occupied by a buffer in ASCII format
351 the result includes the null termination
354 _PUBLIC_ size_t ascii_len_n(const char *src, size_t n);
357 Set a boolean variable from the text value stored in the passed string.
358 Returns true in success, false if the passed string does not correctly
361 _PUBLIC_ bool set_boolean(const char *boolean_string, bool *boolean);
364 * Parse a string containing a boolean value.
366 * val will be set to the read value.
368 * @retval true if a boolean value was parsed, false otherwise.
370 _PUBLIC_ bool conv_str_bool(const char * str, bool * val);
372 #if _SAMBA_BUILD_ == 4
374 * Convert a size specification like 16K into an integral number of bytes.
376 _PUBLIC_ bool conv_str_size(const char * str, uint64_t * val);
380 * Parse a uint64_t value from a string
382 * val will be set to the value read.
384 * @retval true if parsing was successful, false otherwise
386 _PUBLIC_ bool conv_str_u64(const char * str, uint64_t * val);
389 return the number of bytes occupied by a buffer in CH_UTF16 format
390 the result includes the null termination
392 _PUBLIC_ size_t utf16_len(const void *buf);
395 return the number of bytes occupied by a buffer in CH_UTF16 format
396 the result includes the null termination
399 _PUBLIC_ size_t utf16_len_n(const void *src, size_t n);
400 _PUBLIC_ size_t ucs2_align(const void *base_ptr, const void *p, int flags);
403 Do a case-insensitive, whitespace-ignoring string compare.
405 _PUBLIC_ int strwicmp(const char *psz1, const char *psz2);
410 _PUBLIC_ void string_replace(char *s, char oldc, char newc);
415 * @note The comparison is case-insensitive.
417 _PUBLIC_ bool strequal(const char *s1, const char *s2);
419 /* The following definitions come from lib/util/util_strlist.c */
421 /* separators for lists */
423 #define LIST_SEP " \t,\n\r"
427 build an empty (only NULL terminated) list of strings (for expansion with str_list_add() etc)
429 _PUBLIC_ char **str_list_make_empty(TALLOC_CTX *mem_ctx);
432 place the only element 'entry' into a new, NULL terminated string list
434 _PUBLIC_ char **str_list_make_single(TALLOC_CTX *mem_ctx,
438 build a null terminated list of strings from a input string and a
439 separator list. The separator list must contain characters less than
440 or equal to 0x2f for this to work correctly on multi-byte strings
442 _PUBLIC_ char **str_list_make(TALLOC_CTX *mem_ctx, const char *string,
446 * build a null terminated list of strings from an argv-like input string
447 * Entries are separated by spaces and can be enclosed by quotes.
448 * Does NOT support escaping
450 _PUBLIC_ char **str_list_make_shell(TALLOC_CTX *mem_ctx, const char *string, const char *sep);
453 * join a list back to one string
455 _PUBLIC_ char *str_list_join(TALLOC_CTX *mem_ctx, const char **list, char separator);
457 /** join a list back to one (shell-like) string; entries
458 * separated by spaces, using quotes where necessary */
459 _PUBLIC_ char *str_list_join_shell(TALLOC_CTX *mem_ctx, const char **list, char sep);
462 return the number of elements in a string list
464 _PUBLIC_ size_t str_list_length(const char * const *list);
469 _PUBLIC_ char **str_list_copy(TALLOC_CTX *mem_ctx, const char **list);
472 Return true if all the elements of the list match exactly.
474 _PUBLIC_ bool str_list_equal(const char * const *list1, const char * const *list2);
477 add an entry to a string list
479 _PUBLIC_ const char **str_list_add(const char **list, const char *s);
482 remove an entry from a string list
484 _PUBLIC_ void str_list_remove(const char **list, const char *s);
487 return true if a string is in a list
489 _PUBLIC_ bool str_list_check(const char **list, const char *s);
492 return true if a string is in a list, case insensitively
494 _PUBLIC_ bool str_list_check_ci(const char **list, const char *s);
496 append one list to another - expanding list1
498 _PUBLIC_ const char **str_list_append(const char **list1,
499 const char * const *list2);
502 remove duplicate elements from a list
504 _PUBLIC_ const char **str_list_unique(const char **list);
507 very useful when debugging complex list related code
509 _PUBLIC_ void str_list_show(const char **list);
513 append one list to another - expanding list1
514 this assumes the elements of list2 are const pointers, so we can re-use them
516 _PUBLIC_ const char **str_list_append_const(const char **list1,
520 add an entry to a string list
521 this assumes s will not change
523 _PUBLIC_ const char **str_list_add_const(const char **list, const char *s);
527 this assumes list will not change
529 _PUBLIC_ const char **str_list_copy_const(TALLOC_CTX *mem_ctx,
533 * Needed for making an "unconst" list "const"
535 _PUBLIC_ const char **const_str_list(char **list);
538 /* The following definitions come from lib/util/util_file.c */
542 read a line from a file with possible \ continuation chars.
543 Blanks at the start or end of a line are stripped.
544 The string will be allocated if s2 is NULL
546 _PUBLIC_ char *fgets_slash(char *s2,int maxlen,XFILE *f);
549 * Read one line (data until next newline or eof) and allocate it
551 _PUBLIC_ char *afdgets(int fd, TALLOC_CTX *mem_ctx, size_t hint);
554 load a file into memory from a fd.
556 _PUBLIC_ char *fd_load(int fd, size_t *size, size_t maxsize, TALLOC_CTX *mem_ctx);
559 char **file_lines_parse(char *p, size_t size, int *numlines, TALLOC_CTX *mem_ctx);
562 load a file into memory
564 _PUBLIC_ char *file_load(const char *fname, size_t *size, size_t maxsize, TALLOC_CTX *mem_ctx);
567 mmap (if possible) or read a file
569 _PUBLIC_ void *map_file(const char *fname, size_t size);
572 load a file into memory and return an array of pointers to lines in the file
573 must be freed with talloc_free().
575 _PUBLIC_ char **file_lines_load(const char *fname, int *numlines, size_t maxsize, TALLOC_CTX *mem_ctx);
578 load a fd into memory and return an array of pointers to lines in the file
579 must be freed with talloc_free(). If convert is true calls unix_to_dos on
582 _PUBLIC_ char **fd_lines_load(int fd, int *numlines, size_t maxsize, TALLOC_CTX *mem_ctx);
585 take a list of lines and modify them to produce a list where \ continues
588 _PUBLIC_ void file_lines_slashcont(char **lines);
591 save a lump of data into a file. Mostly used for debugging
593 _PUBLIC_ bool file_save(const char *fname, const void *packet, size_t length);
594 _PUBLIC_ int vfdprintf(int fd, const char *format, va_list ap) PRINTF_ATTRIBUTE(2,0);
595 _PUBLIC_ int fdprintf(int fd, const char *format, ...) PRINTF_ATTRIBUTE(2,3);
596 _PUBLIC_ bool large_file_support(const char *path);
599 compare two files, return true if the two files have the same content
601 bool file_compare(const char *path1, const char *path2);
603 /* The following definitions come from lib/util/util.c */
607 Find a suitable temporary directory. The result should be copied immediately
608 as it may be overwritten by a subsequent call.
610 _PUBLIC_ const char *tmpdir(void);
613 Check if a file exists - call vfs_file_exist for samba files.
615 _PUBLIC_ bool file_exist(const char *fname);
618 Check a files mod time.
620 _PUBLIC_ time_t file_modtime(const char *fname);
623 Check if a directory exists.
625 _PUBLIC_ bool directory_exist(const char *dname);
628 * Try to create the specified directory if it didn't exist.
630 * @retval true if the directory already existed and has the right permissions
631 * or was successfully created.
633 _PUBLIC_ bool directory_create_or_exist(const char *dname, uid_t uid,
637 Set a fd into blocking/nonblocking mode. Uses POSIX O_NONBLOCK if available,
642 _PUBLIC_ int set_blocking(int fd, bool set);
645 Sleep for a specified number of milliseconds.
647 _PUBLIC_ void smb_msleep(unsigned int t);
650 Get my own name, return in talloc'ed storage.
652 _PUBLIC_ char* get_myname(TALLOC_CTX *mem_ctx);
655 Check if a process exists. Does this work on all unixes?
657 _PUBLIC_ bool process_exists_by_pid(pid_t pid);
660 Simple routine to do POSIX file locking. Cruft in NFS and 64->32 bit mapping
661 is dealt with in posix.c
663 _PUBLIC_ bool fcntl_lock(int fd, int op, off_t offset, off_t count, int type);
666 * Write dump of binary data to a callback
668 void dump_data_cb(const uint8_t *buf, int len,
669 bool omit_zero_bytes,
670 void (*cb)(const char *buf, void *private_data),
674 * Write dump of binary data to the log file.
676 * The data is only written if the log level is at least level.
678 _PUBLIC_ void dump_data(int level, const uint8_t *buf,int len);
681 * Write dump of binary data to the log file.
683 * The data is only written if the log level is at least level.
684 * 16 zero bytes in a row are omitted
686 _PUBLIC_ void dump_data_skip_zeros(int level, const uint8_t *buf, int len);
689 malloc that aborts with smb_panic on fail or zero size.
691 _PUBLIC_ void *smb_xmalloc(size_t size);
694 Memdup with smb_panic on fail.
696 _PUBLIC_ void *smb_xmemdup(const void *p, size_t size);
699 strdup that aborts on malloc fail.
701 _PUBLIC_ char *smb_xstrdup(const char *s);
703 char *smb_xstrndup(const char *s, size_t n);
706 Like strdup but for memory.
708 _PUBLIC_ void *memdup(const void *p, size_t size);
711 * Write a password to the log file.
713 * @note Only actually does something if DEBUG_PASSWORD was defined during
716 _PUBLIC_ void dump_data_pw(const char *msg, const uint8_t * data, size_t len);
719 * see if a range of memory is all zero. A NULL pointer is considered
722 _PUBLIC_ bool all_zero(const uint8_t *ptr, size_t size);
725 realloc an array, checking for integer overflow in the array size
727 _PUBLIC_ void *realloc_array(void *ptr, size_t el_size, unsigned count, bool free_on_fail);
729 void *malloc_array(size_t el_size, unsigned int count);
731 /* The following definitions come from lib/util/fsusage.c */
735 * Retrieve amount of free disk space.
736 * this does all of the system specific guff to get the free disk space.
737 * It is derived from code in the GNU fileutils package, but has been
738 * considerably mangled for use here
740 * results are returned in *dfree and *dsize, in 512 byte units
742 _PUBLIC_ int sys_fsusage(const char *path, uint64_t *dfree, uint64_t *dsize);
744 /* The following definitions come from lib/util/ms_fnmatch.c */
749 * @brief MS-style Filename matching
752 #if _SAMBA_BUILD_ == 4
753 /* protocol types. It assumes that higher protocols include lower protocols
754 as subsets. FIXME: Move to one of the smb-specific headers */
755 enum protocol_types {
765 int ms_fnmatch(const char *pattern, const char *string, enum protocol_types protocol);
767 /** a generic fnmatch function - uses for non-CIFS pattern matching */
768 int gen_fnmatch(const char *pattern, const char *string);
771 /* The following definitions come from lib/util/idtree.c */
775 initialise a idr tree. The context return value must be passed to
776 all subsequent idr calls. To destroy the idr tree use talloc_free()
779 _PUBLIC_ struct idr_context *idr_init(TALLOC_CTX *mem_ctx);
782 allocate the next available id, and assign 'ptr' into its slot.
783 you can retrieve later this pointer using idr_find()
785 _PUBLIC_ int idr_get_new(struct idr_context *idp, void *ptr, int limit);
788 allocate a new id, giving the first available value greater than or
789 equal to the given starting id
791 _PUBLIC_ int idr_get_new_above(struct idr_context *idp, void *ptr, int starting_id, int limit);
794 allocate a new id randomly in the given range
796 _PUBLIC_ int idr_get_new_random(struct idr_context *idp, void *ptr, int limit);
799 find a pointer value previously set with idr_get_new given an id
801 _PUBLIC_ void *idr_find(struct idr_context *idp, int id);
804 remove an id from the idr tree
806 _PUBLIC_ int idr_remove(struct idr_context *idp, int id);
808 /* The following definitions come from lib/util/become_daemon.c */
811 Close the low 3 fd's and open dev/null in their place
813 _PUBLIC_ void close_low_fds(bool stderr_too);
816 Become a daemon, discarding the controlling terminal.
818 _PUBLIC_ void become_daemon(bool do_fork, bool no_process_group, bool log_stdout);
821 * Load a ini-style file.
823 bool pm_process( const char *fileName,
824 bool (*sfunc)(const char *, void *),
825 bool (*pfunc)(const char *, const char *, void *),
828 bool unmap_file(void *start, size_t size);
830 void print_asc(int level, const uint8_t *buf,int len);
831 void print_asc_cb(const uint8_t *buf, int len,
832 void (*cb)(const char *buf, void *private_data),
836 * Add an id to an array of ids.
838 * num should be a pointer to an integer that holds the current
839 * number of elements in ids. It will be updated by this function.
842 bool add_uid_to_array_unique(TALLOC_CTX *mem_ctx, uid_t uid,
843 uid_t **uids, uint32_t *num_uids);
844 bool add_gid_to_array_unique(TALLOC_CTX *mem_ctx, gid_t gid,
845 gid_t **gids, uint32_t *num_gids);
848 * Allocate anonymous shared memory of the given size
850 void *anonymous_shared_allocate(size_t bufsz);
851 void anonymous_shared_free(void *ptr);
854 run a command as a child process, with a timeout.
856 any stdout/stderr from the child will appear in the Samba logs with
857 the specified log levels
859 If callback is set then the callback is called on completion
860 with the return code from the command
862 struct tevent_context;
864 struct tevent_req *samba_runcmd_send(TALLOC_CTX *mem_ctx,
865 struct tevent_context *ev,
866 struct timeval endtime,
867 int stdout_log_level,
868 int stderr_log_level,
869 const char * const *argv0, ...);
870 int samba_runcmd_recv(struct tevent_req *req, int *perrno);
873 void samba_start_debugger(void);
876 #endif /* _SAMBA_UTIL_H_ */