ctdb/lib/util/util.h

   1 /*
   2    Unix SMB/CIFS implementation.
   3    Utility functions for Samba
   4    Copyright (C) Andrew Tridgell 1992-1999
   5    Copyright (C) Jelmer Vernooij 2005
   6
   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.
  11
  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.
  16
  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/>.
  19 */
  20
  21 #ifndef _SAMBA_UTIL_H_
  22 #define _SAMBA_UTIL_H_
  23
  24 /**
  25  * @file
  26  * @brief Helpful macros
  27  */
  28
  29 struct smbsrv_tcon;
  30
  31 #ifdef _SAMBA_BUILD_
  32 extern const char *logfile;
  33 #endif
  34 extern const char *panic_action;
  35 extern void (*pre_panic_action_hook)(void);
  36 extern void (*post_panic_action_hook)(void);
  37
  38 /**
  39  * assert macros
  40  */
  41 #ifdef DEVELOPER
  42 #define SMB_ASSERT(b) do { if (!(b)) { \
  43         DEBUG(0,("PANIC: assert failed at %s(%d): %s\n", \
  44                  __FILE__, __LINE__, #b)); smb_panic("assert failed: " #b); }} while(0)
  45 #else
  46 /* redefine the assert macro for non-developer builds */
  47 #define SMB_ASSERT(b) do { if (!(b)) { \
  48         DEBUG(0,("PANIC: assert failed at %s(%d): %s\n", \
  49             __FILE__, __LINE__, #b)); }} while (0)
  50 #endif
  51
  52 #if _SAMBA_BUILD_ == 4
  53 #ifdef VALGRIND
  54 #define strlen(x) valgrind_strlen(x)
  55 size_t valgrind_strlen(const char *s);
  56 #endif
  57 #endif
  58
  59 #ifndef ABS
  60 #define ABS(a) ((a)>0?(a):(-(a)))
  61 #endif
  62
  63 /**
  64  * Write backtrace to debug log
  65  */
  66 _PUBLIC_ void call_backtrace(void);
  67
  68 /**
  69  Something really nasty happened - panic !
  70 **/
  71 _PUBLIC_ _NORETURN_ void smb_panic(const char *why);
  72
  73 /**
  74 setup our fault handlers
  75 **/
  76 _PUBLIC_ void fault_setup(const char *pname);
  77
  78 /**
  79   register a fault handler.
  80   Should only be called once in the execution of smbd.
  81 */
  82 _PUBLIC_ bool register_fault_handler(const char *name, void (*fault_handler)(int sig));
  83
  84 /* The following definitions come from lib/util/signal.c  */
  85
  86
  87 /**
  88  Block sigs.
  89 **/
  90 void BlockSignals(bool block, int signum);
  91
  92 /**
  93  Catch a signal. This should implement the following semantics:
  94
  95  1) The handler remains installed after being called.
  96  2) The signal should be blocked during handler execution.
  97 **/
  98 void (*CatchSignal(int signum,void (*handler)(int )))(int);
  99
 100 /**
 101  Ignore SIGCLD via whatever means is necessary for this OS.
 102 **/
 103 void CatchChild(void);
 104
 105 /**
 106  Catch SIGCLD but leave the child around so it's status can be reaped.
 107 **/
 108 void CatchChildLeaveStatus(void);
 109
 110
 111 /* The following definitions come from lib/util/util_str.c  */
 112
 113
 114 /**
 115  Trim the specified elements off the front and back of a string.
 116 **/
 117 _PUBLIC_ bool trim_string(char *s, const char *front, const char *back);
 118
 119 /**
 120  Find the number of 'c' chars in a string
 121 **/
 122 _PUBLIC_ _PURE_ size_t count_chars(const char *s, char c);
 123
 124 /**
 125  Safe string copy into a known length string. maxlength does not
 126  include the terminating zero.
 127 **/
 128 _PUBLIC_ char *safe_strcpy(char *dest,const char *src, size_t maxlength);
 129
 130 /**
 131  Safe string cat into a string. maxlength does not
 132  include the terminating zero.
 133 **/
 134 _PUBLIC_ char *safe_strcat(char *dest, const char *src, size_t maxlength);
 135
 136 /**
 137  Routine to get hex characters and turn them into a 16 byte array.
 138  the array can be variable length, and any non-hex-numeric
 139  characters are skipped.  "0xnn" or "0Xnn" is specially catered
 140  for.
 141
 142  valid examples: "0A5D15"; "0x15, 0x49, 0xa2"; "59\ta9\te3\n"
 143
 144
 145 **/
 146 _PUBLIC_ size_t strhex_to_str(char *p, size_t p_len, const char *strhex, size_t strhex_len);
 147
 148 #ifdef _SAMBA_BUILD_
 149 /**
 150  * Parse a hex string and return a data blob.
 151  */
 152 _PUBLIC_ _PURE_ DATA_BLOB strhex_to_data_blob(TALLOC_CTX *mem_ctx, const char *strhex) ;
 153 #endif
 154
 155 /**
 156  * Routine to print a buffer as HEX digits, into an allocated string.
 157  */
 158 _PUBLIC_ void hex_encode(const unsigned char *buff_in, size_t len, char **out_hex_buffer);
 159
 160 /**
 161  * talloc version of hex_encode()
 162  */
 163 _PUBLIC_ char *hex_encode_talloc(TALLOC_CTX *mem_ctx, const unsigned char *buff_in, size_t len);
 164
 165 /**
 166  Substitute a string for a pattern in another string. Make sure there is
 167  enough room!
 168
 169  This routine looks for pattern in s and replaces it with
 170  insert. It may do multiple replacements.
 171
 172  Any of " ; ' $ or ` in the insert string are replaced with _
 173  if len==0 then the string cannot be extended. This is different from the old
 174  use of len==0 which was for no length checks to be done.
 175 **/
 176 _PUBLIC_ void string_sub(char *s,const char *pattern, const char *insert, size_t len);
 177
 178
 179 _PUBLIC_ char *string_sub_talloc(TALLOC_CTX *mem_ctx, const char *s,
 180                                 const char *pattern, const char *insert);
 181
 182 /**
 183  Similar to string_sub() but allows for any character to be substituted.
 184  Use with caution!
 185  if len==0 then the string cannot be extended. This is different from the old
 186  use of len==0 which was for no length checks to be done.
 187 **/
 188 _PUBLIC_ void all_string_sub(char *s,const char *pattern,const char *insert, size_t len);
 189
 190 /**
 191  Unescape a URL encoded string, in place.
 192 **/
 193 _PUBLIC_ void rfc1738_unescape(char *buf);
 194
 195 /**
 196   format a string into length-prefixed dotted domain format, as used in NBT
 197   and in some ADS structures
 198 **/
 199 _PUBLIC_ const char *str_format_nbt_domain(TALLOC_CTX *mem_ctx, const char *s);
 200
 201 /**
 202  * Add a string to an array of strings.
 203  *
 204  * num should be a pointer to an integer that holds the current
 205  * number of elements in strings. It will be updated by this function.
 206  */
 207 _PUBLIC_ bool add_string_to_array(TALLOC_CTX *mem_ctx,
 208                          const char *str, const char ***strings, int *num);
 209
 210 /**
 211   varient of strcmp() that handles NULL ptrs
 212 **/
 213 _PUBLIC_ int strcmp_safe(const char *s1, const char *s2);
 214
 215 /**
 216 return the number of bytes occupied by a buffer in ASCII format
 217 the result includes the null termination
 218 limited by 'n' bytes
 219 **/
 220 _PUBLIC_ size_t ascii_len_n(const char *src, size_t n);
 221
 222 /**
 223  Set a boolean variable from the text value stored in the passed string.
 224  Returns true in success, false if the passed string does not correctly
 225  represent a boolean.
 226 **/
 227 _PUBLIC_ bool set_boolean(const char *boolean_string, bool *boolean);
 228
 229 /**
 230  * Parse a string containing a boolean value.
 231  *
 232  * val will be set to the read value.
 233  *
 234  * @retval true if a boolean value was parsed, false otherwise.
 235  */
 236 _PUBLIC_ bool conv_str_bool(const char * str, bool * val);
 237
 238 #if _SAMBA_BUILD_ == 4
 239 /**
 240  * Convert a size specification like 16K into an integral number of bytes.
 241  **/
 242 _PUBLIC_ bool conv_str_size(const char * str, uint64_t * val);
 243 #endif
 244
 245 /**
 246  * Parse a uint64_t value from a string
 247  *
 248  * val will be set to the value read.
 249  *
 250  * @retval true if parsing was successful, false otherwise
 251  */
 252 _PUBLIC_ bool conv_str_u64(const char * str, uint64_t * val);
 253
 254 /**
 255 return the number of bytes occupied by a buffer in CH_UTF16 format
 256 the result includes the null termination
 257 **/
 258 _PUBLIC_ size_t utf16_len(const void *buf);
 259
 260 /**
 261 return the number of bytes occupied by a buffer in CH_UTF16 format
 262 the result includes the null termination
 263 limited by 'n' bytes
 264 **/
 265 _PUBLIC_ size_t utf16_len_n(const void *src, size_t n);
 266 _PUBLIC_ size_t ucs2_align(const void *base_ptr, const void *p, int flags);
 267
 268 /**
 269 Do a case-insensitive, whitespace-ignoring string compare.
 270 **/
 271 _PUBLIC_ int strwicmp(const char *psz1, const char *psz2);
 272
 273 /**
 274  String replace.
 275 **/
 276 _PUBLIC_ void string_replace(char *s, char oldc, char newc);
 277
 278 /**
 279  * Compare 2 strings.
 280  *
 281  * @note The comparison is case-insensitive.
 282  **/
 283 _PUBLIC_ bool strequal(const char *s1, const char *s2);
 284
 285 /* The following definitions come from lib/util/util_strlist.c  */
 286 #ifdef _SAMBA_BUILD_
 287
 288 /* separators for lists */
 289 #ifndef LIST_SEP
 290 #define LIST_SEP " \t,\n\r"
 291 #endif
 292
 293 /**
 294   build a null terminated list of strings from a input string and a
 295   separator list. The separator list must contain characters less than
 296   or equal to 0x2f for this to work correctly on multi-byte strings
 297 */
 298 _PUBLIC_ char **str_list_make(TALLOC_CTX *mem_ctx, const char *string, const char *sep);
 299
 300 /**
 301  * build a null terminated list of strings from an argv-like input string
 302  * Entries are seperated by spaces and can be enclosed by quotes.
 303  * Does NOT support escaping
 304  */
 305 _PUBLIC_ const char **str_list_make_shell(TALLOC_CTX *mem_ctx, const char *string, const char *sep);
 306
 307 /**
 308  * join a list back to one string
 309  */
 310 _PUBLIC_ char *str_list_join(TALLOC_CTX *mem_ctx, const char **list, char seperator);
 311
 312 /** join a list back to one (shell-like) string; entries
 313  * seperated by spaces, using quotes where necessary */
 314 _PUBLIC_ char *str_list_join_shell(TALLOC_CTX *mem_ctx, const char **list, char sep);
 315
 316 /**
 317   return the number of elements in a string list
 318 */
 319 _PUBLIC_ size_t str_list_length(const char * const *list);
 320
 321 /**
 322   copy a string list
 323 */
 324 _PUBLIC_ char **str_list_copy(TALLOC_CTX *mem_ctx, const char **list);
 325
 326 /**
 327    Return true if all the elements of the list match exactly.
 328  */
 329 _PUBLIC_ bool str_list_equal(const char **list1, const char **list2);
 330
 331 /**
 332   add an entry to a string list
 333 */
 334 _PUBLIC_ const char **str_list_add(const char **list, const char *s);
 335
 336 /**
 337   remove an entry from a string list
 338 */
 339 _PUBLIC_ void str_list_remove(const char **list, const char *s);
 340
 341 /**
 342   return true if a string is in a list
 343 */
 344 _PUBLIC_ bool str_list_check(const char **list, const char *s);
 345
 346 /**
 347   return true if a string is in a list, case insensitively
 348 */
 349 _PUBLIC_ bool str_list_check_ci(const char **list, const char *s);
 350 #endif
 351
 352 /* The following definitions come from lib/util/util_file.c  */
 353
 354
 355 #ifdef _SAMBA_BUILD_
 356 /**
 357 read a line from a file with possible \ continuation chars.
 358 Blanks at the start or end of a line are stripped.
 359 The string will be allocated if s2 is NULL
 360 **/
 361 _PUBLIC_ char *fgets_slash(char *s2,int maxlen,XFILE *f);
 362 #endif
 363
 364 /**
 365  * Read one line (data until next newline or eof) and allocate it
 366  */
 367 _PUBLIC_ char *afdgets(int fd, TALLOC_CTX *mem_ctx, size_t hint);
 368
 369 #ifdef _SAMBA_BUILD_
 370 /**
 371 load a file into memory from a fd.
 372 **/
 373 _PUBLIC_ char *fd_load(int fd, size_t *size, size_t maxsize, TALLOC_CTX *mem_ctx);
 374
 375
 376 char **file_lines_parse(char *p, size_t size, int *numlines, TALLOC_CTX *mem_ctx);
 377
 378 /**
 379 load a file into memory
 380 **/
 381 _PUBLIC_ char *file_load(const char *fname, size_t *size, size_t maxsize, TALLOC_CTX *mem_ctx);
 382 #endif
 383
 384 /**
 385 mmap (if possible) or read a file
 386 **/
 387 _PUBLIC_ void *map_file(const char *fname, size_t size);
 388
 389 #ifdef _SAMBA_BUILD_
 390 /**
 391 load a file into memory and return an array of pointers to lines in the file
 392 must be freed with talloc_free().
 393 **/
 394 _PUBLIC_ char **file_lines_load(const char *fname, int *numlines, size_t maxsize, TALLOC_CTX *mem_ctx);
 395 #endif
 396
 397 /**
 398 load a fd into memory and return an array of pointers to lines in the file
 399 must be freed with talloc_free(). If convert is true calls unix_to_dos on
 400 the list.
 401 **/
 402 _PUBLIC_ char **fd_lines_load(int fd, int *numlines, size_t maxsize, TALLOC_CTX *mem_ctx);
 403
 404 /**
 405 take a list of lines and modify them to produce a list where \ continues
 406 a line
 407 **/
 408 _PUBLIC_ void file_lines_slashcont(char **lines);
 409
 410 /**
 411   save a lump of data into a file. Mostly used for debugging
 412 */
 413 _PUBLIC_ bool file_save(const char *fname, const void *packet, size_t length);
 414 _PUBLIC_ int vfdprintf(int fd, const char *format, va_list ap) PRINTF_ATTRIBUTE(2,0);
 415 _PUBLIC_ int fdprintf(int fd, const char *format, ...) PRINTF_ATTRIBUTE(2,3);
 416 _PUBLIC_ bool large_file_support(const char *path);
 417
 418 /* The following definitions come from lib/util/util.c  */
 419
 420
 421 /**
 422  Find a suitable temporary directory. The result should be copied immediately
 423  as it may be overwritten by a subsequent call.
 424 **/
 425 _PUBLIC_ const char *tmpdir(void);
 426
 427 /**
 428  Check if a file exists - call vfs_file_exist for samba files.
 429 **/
 430 _PUBLIC_ bool file_exist(const char *fname);
 431
 432 /**
 433  Check a files mod time.
 434 **/
 435 _PUBLIC_ time_t file_modtime(const char *fname);
 436
 437 /**
 438  Check if a directory exists.
 439 **/
 440 _PUBLIC_ bool directory_exist(const char *dname);
 441
 442 /**
 443  * Try to create the specified directory if it didn't exist.
 444  *
 445  * @retval true if the directory already existed and has the right permissions
 446  * or was successfully created.
 447  */
 448 _PUBLIC_ bool directory_create_or_exist(const char *dname, uid_t uid,
 449                                mode_t dir_perms);
 450
 451 /**
 452  Set a fd into blocking/nonblocking mode. Uses POSIX O_NONBLOCK if available,
 453  else
 454   if SYSV use O_NDELAY
 455   if BSD use FNDELAY
 456 **/
 457 _PUBLIC_ int set_blocking(int fd, bool set);
 458
 459 /**
 460  Sleep for a specified number of milliseconds.
 461 **/
 462 _PUBLIC_ void msleep(unsigned int t);
 463
 464 /**
 465  Get my own name, return in malloc'ed storage.
 466 **/
 467 _PUBLIC_ char* get_myname(void);
 468
 469 /**
 470  Return true if a string could be a pure IP address.
 471 **/
 472 _PUBLIC_ bool is_ipaddress(const char *str);
 473
 474 /**
 475  Interpret an internet address or name into an IP address in 4 byte form.
 476 **/
 477 _PUBLIC_ uint32_t interpret_addr(const char *str);
 478
 479 /**
 480  A convenient addition to interpret_addr().
 481 **/
 482 _PUBLIC_ struct in_addr interpret_addr2(const char *str);
 483
 484 /**
 485  Check if an IP is the 0.0.0.0.
 486 **/
 487 _PUBLIC_ bool is_zero_ip_v4(struct in_addr ip);
 488
 489 /**
 490  Are two IPs on the same subnet?
 491 **/
 492 _PUBLIC_ bool same_net_v4(struct in_addr ip1,struct in_addr ip2,struct in_addr mask);
 493
 494 _PUBLIC_ bool is_ipaddress_v4(const char *str);
 495
 496 /**
 497  Check if a process exists. Does this work on all unixes?
 498 **/
 499 _PUBLIC_ bool process_exists_by_pid(pid_t pid);
 500
 501 /**
 502  Simple routine to do POSIX file locking. Cruft in NFS and 64->32 bit mapping
 503  is dealt with in posix.c
 504 **/
 505 _PUBLIC_ bool fcntl_lock(int fd, int op, off_t offset, off_t count, int type);
 506
 507 /**
 508  malloc that aborts with smb_panic on fail or zero size.
 509 **/
 510 _PUBLIC_ void *smb_xmalloc(size_t size);
 511
 512 /**
 513  Memdup with smb_panic on fail.
 514 **/
 515 _PUBLIC_ void *smb_xmemdup(const void *p, size_t size);
 516
 517 /**
 518  strdup that aborts on malloc fail.
 519 **/
 520 _PUBLIC_ char *smb_xstrdup(const char *s);
 521
 522 char *smb_xstrndup(const char *s, size_t n);
 523
 524 /**
 525  Like strdup but for memory.
 526 **/
 527 _PUBLIC_ void *smb_memdup(const void *p, size_t size);
 528
 529 /**
 530  * see if a range of memory is all zero. A NULL pointer is considered
 531  * to be all zero
 532  */
 533 _PUBLIC_ bool all_zero(const uint8_t *ptr, size_t size);
 534
 535 /**
 536   realloc an array, checking for integer overflow in the array size
 537 */
 538 _PUBLIC_ void *realloc_array(void *ptr, size_t el_size, unsigned count, bool free_on_fail);
 539
 540 void *malloc_array(size_t el_size, unsigned int count);
 541
 542 /* The following definitions come from lib/util/fsusage.c  */
 543
 544
 545 /**
 546  * Retrieve amount of free disk space.
 547  * this does all of the system specific guff to get the free disk space.
 548  * It is derived from code in the GNU fileutils package, but has been
 549  * considerably mangled for use here
 550  *
 551  * results are returned in *dfree and *dsize, in 512 byte units
 552 */
 553 _PUBLIC_ int sys_fsusage(const char *path, uint64_t *dfree, uint64_t *dsize);
 554
 555 /* The following definitions come from lib/util/ms_fnmatch.c  */
 556
 557
 558 /**
 559  * @file
 560  * @brief MS-style Filename matching
 561  */
 562
 563 #if _SAMBA_BUILD_ == 4
 564 /* protocol types. It assumes that higher protocols include lower protocols
 565    as subsets. FIXME: Move to one of the smb-specific headers */
 566 enum protocol_types {
 567         PROTOCOL_NONE,
 568         PROTOCOL_CORE,
 569         PROTOCOL_COREPLUS,
 570         PROTOCOL_LANMAN1,
 571         PROTOCOL_LANMAN2,
 572         PROTOCOL_NT1,
 573         PROTOCOL_SMB2
 574 };
 575
 576 int ms_fnmatch(const char *pattern, const char *string, enum protocol_types protocol);
 577
 578 /** a generic fnmatch function - uses for non-CIFS pattern matching */
 579 int gen_fnmatch(const char *pattern, const char *string);
 580 #endif
 581
 582 /* The following definitions come from lib/util/mutex.c  */
 583
 584
 585 #ifdef _SAMBA_BUILD_
 586 /**
 587   register a set of mutex/rwlock handlers.
 588   Should only be called once in the execution of smbd.
 589 */
 590 _PUBLIC_ bool register_mutex_handlers(const char *name, struct mutex_ops *ops);
 591 #endif
 592
 593 /* The following definitions come from lib/util/idtree.c  */
 594
 595
 596 /**
 597   initialise a idr tree. The context return value must be passed to
 598   all subsequent idr calls. To destroy the idr tree use talloc_free()
 599   on this context
 600  */
 601 _PUBLIC_ struct idr_context *idr_init(TALLOC_CTX *mem_ctx);
 602
 603 /**
 604   allocate the next available id, and assign 'ptr' into its slot.
 605   you can retrieve later this pointer using idr_find()
 606 */
 607 _PUBLIC_ int idr_get_new(struct idr_context *idp, void *ptr, int limit);
 608
 609 /**
 610    allocate a new id, giving the first available value greater than or
 611    equal to the given starting id
 612 */
 613 _PUBLIC_ int idr_get_new_above(struct idr_context *idp, void *ptr, int starting_id, int limit);
 614
 615 /**
 616   allocate a new id randomly in the given range
 617 */
 618 _PUBLIC_ int idr_get_new_random(struct idr_context *idp, void *ptr, int limit);
 619
 620 /**
 621   find a pointer value previously set with idr_get_new given an id
 622 */
 623 _PUBLIC_ void *idr_find(struct idr_context *idp, int id);
 624
 625 /**
 626   remove an id from the idr tree
 627 */
 628 _PUBLIC_ int idr_remove(struct idr_context *idp, int id);
 629
 630 /* The following definitions come from lib/util/become_daemon.c  */
 631
 632 #if _SAMBA_BUILD_ == 4
 633 /**
 634  Become a daemon, discarding the controlling terminal.
 635 **/
 636 _PUBLIC_ void become_daemon(bool fork);
 637 #endif
 638
 639 /**
 640  * Load a ini-style file.
 641  */
 642 bool pm_process( const char *fileName,
 643                  bool (*sfunc)(const char *, void *),
 644                  bool (*pfunc)(const char *, const char *, void *),
 645                                  void *userdata);
 646
 647 bool unmap_file(void *start, size_t size);
 648
 649 #define CONST_DISCARD(type, ptr)      ((type) ((void *) (ptr)))
 650
 651 #endif /* _SAMBA_UTIL_H_ */