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(void);
  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_file.c  */
 286
 287
 288 #ifdef _SAMBA_BUILD_
 289 /**
 290 read a line from a file with possible \ continuation chars.
 291 Blanks at the start or end of a line are stripped.
 292 The string will be allocated if s2 is NULL
 293 **/
 294 _PUBLIC_ char *fgets_slash(char *s2,int maxlen,XFILE *f);
 295 #endif
 296
 297 /**
 298  * Read one line (data until next newline or eof) and allocate it
 299  */
 300 _PUBLIC_ char *afdgets(int fd, TALLOC_CTX *mem_ctx, size_t hint);
 301
 302 #ifdef _SAMBA_BUILD_
 303 /**
 304 load a file into memory from a fd.
 305 **/
 306 _PUBLIC_ char *fd_load(int fd, size_t *size, size_t maxsize, TALLOC_CTX *mem_ctx);
 307
 308
 309 char **file_lines_parse(char *p, size_t size, int *numlines, TALLOC_CTX *mem_ctx);
 310
 311 /**
 312 load a file into memory
 313 **/
 314 _PUBLIC_ char *file_load(const char *fname, size_t *size, size_t maxsize, TALLOC_CTX *mem_ctx);
 315 #endif
 316
 317 /**
 318 mmap (if possible) or read a file
 319 **/
 320 _PUBLIC_ void *map_file(const char *fname, size_t size);
 321
 322 /**
 323 load a file into memory and return an array of pointers to lines in the file
 324 must be freed with talloc_free().
 325 **/
 326 _PUBLIC_ char **file_lines_load(const char *fname, int *numlines, size_t maxsize, TALLOC_CTX *mem_ctx);
 327
 328 /**
 329 load a fd into memory and return an array of pointers to lines in the file
 330 must be freed with talloc_free(). If convert is true calls unix_to_dos on
 331 the list.
 332 **/
 333 _PUBLIC_ char **fd_lines_load(int fd, int *numlines, size_t maxsize, TALLOC_CTX *mem_ctx);
 334
 335 /**
 336 take a list of lines and modify them to produce a list where \ continues
 337 a line
 338 **/
 339 _PUBLIC_ void file_lines_slashcont(char **lines);
 340
 341 /**
 342   save a lump of data into a file. Mostly used for debugging
 343 */
 344 _PUBLIC_ bool file_save(const char *fname, const void *packet, size_t length);
 345 _PUBLIC_ int vfdprintf(int fd, const char *format, va_list ap) PRINTF_ATTRIBUTE(2,0);
 346 _PUBLIC_ int fdprintf(int fd, const char *format, ...) PRINTF_ATTRIBUTE(2,3);
 347
 348 /* The following definitions come from lib/util/util.c  */
 349
 350
 351 /**
 352  Find a suitable temporary directory. The result should be copied immediately
 353  as it may be overwritten by a subsequent call.
 354 **/
 355 _PUBLIC_ const char *tmpdir(void);
 356
 357 /**
 358  Check if a file exists - call vfs_file_exist for samba files.
 359 **/
 360 _PUBLIC_ bool file_exist(const char *fname);
 361
 362 /**
 363  Check a files mod time.
 364 **/
 365 _PUBLIC_ time_t file_modtime(const char *fname);
 366
 367 /**
 368  Check if a directory exists.
 369 **/
 370 _PUBLIC_ bool directory_exist(const char *dname);
 371
 372 /**
 373  * Try to create the specified directory if it didn't exist.
 374  *
 375  * @retval true if the directory already existed and has the right permissions
 376  * or was successfully created.
 377  */
 378 _PUBLIC_ bool directory_create_or_exist(const char *dname, uid_t uid,
 379                                mode_t dir_perms);
 380
 381 /**
 382  Set a fd into blocking/nonblocking mode. Uses POSIX O_NONBLOCK if available,
 383  else
 384   if SYSV use O_NDELAY
 385   if BSD use FNDELAY
 386 **/
 387 _PUBLIC_ int set_blocking(int fd, bool set);
 388
 389 /**
 390  Sleep for a specified number of milliseconds.
 391 **/
 392 _PUBLIC_ void msleep(unsigned int t);
 393
 394 /**
 395  Get my own name, return in malloc'ed storage.
 396 **/
 397 _PUBLIC_ char* get_myname(void);
 398
 399 /**
 400  Return true if a string could be a pure IP address.
 401 **/
 402 _PUBLIC_ bool is_ipaddress(const char *str);
 403
 404 /**
 405  Interpret an internet address or name into an IP address in 4 byte form.
 406 **/
 407 _PUBLIC_ uint32_t interpret_addr(const char *str);
 408
 409 /**
 410  A convenient addition to interpret_addr().
 411 **/
 412 _PUBLIC_ struct in_addr interpret_addr2(const char *str);
 413
 414 /**
 415  Check if an IP is the 0.0.0.0.
 416 **/
 417 _PUBLIC_ bool is_zero_ip_v4(struct in_addr ip);
 418
 419 /**
 420  Are two IPs on the same subnet?
 421 **/
 422 _PUBLIC_ bool same_net_v4(struct in_addr ip1,struct in_addr ip2,struct in_addr mask);
 423
 424 _PUBLIC_ bool is_ipaddress_v4(const char *str);
 425
 426 /**
 427  Check if a process exists. Does this work on all unixes?
 428 **/
 429 _PUBLIC_ bool process_exists_by_pid(pid_t pid);
 430
 431 /**
 432  Simple routine to do POSIX file locking. Cruft in NFS and 64->32 bit mapping
 433  is dealt with in posix.c
 434 **/
 435 _PUBLIC_ bool fcntl_lock(int fd, int op, off_t offset, off_t count, int type);
 436
 437 /**
 438  malloc that aborts with smb_panic on fail or zero size.
 439 **/
 440 _PUBLIC_ void *smb_xmalloc(size_t size);
 441
 442 /**
 443  Memdup with smb_panic on fail.
 444 **/
 445 _PUBLIC_ void *smb_xmemdup(const void *p, size_t size);
 446
 447 /**
 448  strdup that aborts on malloc fail.
 449 **/
 450 _PUBLIC_ char *smb_xstrdup(const char *s);
 451
 452 char *smb_xstrndup(const char *s, size_t n);
 453
 454 /**
 455  Like strdup but for memory.
 456 **/
 457 _PUBLIC_ void *smb_memdup(const void *p, size_t size);
 458
 459 /**
 460  * see if a range of memory is all zero. A NULL pointer is considered
 461  * to be all zero
 462  */
 463 _PUBLIC_ bool all_zero(const uint8_t *ptr, size_t size);
 464
 465 /**
 466   realloc an array, checking for integer overflow in the array size
 467 */
 468 _PUBLIC_ void *realloc_array(void *ptr, size_t el_size, unsigned count, bool free_on_fail);
 469
 470 void *malloc_array(size_t el_size, unsigned int count);
 471
 472 /* The following definitions come from lib/util/fsusage.c  */
 473
 474
 475 /**
 476  * Retrieve amount of free disk space.
 477  * this does all of the system specific guff to get the free disk space.
 478  * It is derived from code in the GNU fileutils package, but has been
 479  * considerably mangled for use here
 480  *
 481  * results are returned in *dfree and *dsize, in 512 byte units
 482 */
 483 _PUBLIC_ int sys_fsusage(const char *path, uint64_t *dfree, uint64_t *dsize);
 484
 485 /* The following definitions come from lib/util/ms_fnmatch.c  */
 486
 487
 488 /**
 489  * @file
 490  * @brief MS-style Filename matching
 491  */
 492
 493 #if _SAMBA_BUILD_ == 4
 494 /* protocol types. It assumes that higher protocols include lower protocols
 495    as subsets. FIXME: Move to one of the smb-specific headers */
 496 enum protocol_types {
 497         PROTOCOL_NONE,
 498         PROTOCOL_CORE,
 499         PROTOCOL_COREPLUS,
 500         PROTOCOL_LANMAN1,
 501         PROTOCOL_LANMAN2,
 502         PROTOCOL_NT1,
 503         PROTOCOL_SMB2
 504 };
 505
 506 int ms_fnmatch(const char *pattern, const char *string, enum protocol_types protocol);
 507
 508 /** a generic fnmatch function - uses for non-CIFS pattern matching */
 509 int gen_fnmatch(const char *pattern, const char *string);
 510 #endif
 511
 512 /* The following definitions come from lib/util/mutex.c  */
 513
 514
 515 #ifdef _SAMBA_BUILD_
 516 /**
 517   register a set of mutex/rwlock handlers.
 518   Should only be called once in the execution of smbd.
 519 */
 520 _PUBLIC_ bool register_mutex_handlers(const char *name, struct mutex_ops *ops);
 521 #endif
 522
 523 /* The following definitions come from lib/util/idtree.c  */
 524
 525
 526 /**
 527   initialise a idr tree. The context return value must be passed to
 528   all subsequent idr calls. To destroy the idr tree use talloc_free()
 529   on this context
 530  */
 531 _PUBLIC_ struct idr_context *idr_init(TALLOC_CTX *mem_ctx);
 532
 533 /**
 534   allocate the next available id, and assign 'ptr' into its slot.
 535   you can retrieve later this pointer using idr_find()
 536 */
 537 _PUBLIC_ int idr_get_new(struct idr_context *idp, void *ptr, int limit);
 538
 539 /**
 540    allocate a new id, giving the first available value greater than or
 541    equal to the given starting id
 542 */
 543 _PUBLIC_ int idr_get_new_above(struct idr_context *idp, void *ptr, int starting_id, int limit);
 544
 545 /**
 546   allocate a new id randomly in the given range
 547 */
 548 _PUBLIC_ int idr_get_new_random(struct idr_context *idp, void *ptr, int limit);
 549
 550 /**
 551   find a pointer value previously set with idr_get_new given an id
 552 */
 553 _PUBLIC_ void *idr_find(struct idr_context *idp, int id);
 554
 555 /**
 556   remove an id from the idr tree
 557 */
 558 _PUBLIC_ int idr_remove(struct idr_context *idp, int id);
 559
 560 /* The following definitions come from lib/util/become_daemon.c  */
 561
 562 #if _SAMBA_BUILD_ == 4
 563 /**
 564  Become a daemon, discarding the controlling terminal.
 565 **/
 566 _PUBLIC_ void become_daemon(bool fork);
 567 #endif
 568
 569 /**
 570  * Load a ini-style file.
 571  */
 572 bool pm_process( const char *fileName,
 573                  bool (*sfunc)(const char *, void *),
 574                  bool (*pfunc)(const char *, const char *, void *),
 575                                  void *userdata);
 576
 577 bool unmap_file(void *start, size_t size);
 578
 579 #define CONST_DISCARD(type, ptr)      ((type) ((void *) (ptr)))
 580
 581 #endif /* _SAMBA_UTIL_H_ */