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))(int);
 104
 105 /**
 106  Catch SIGCLD but leave the child around so it's status can be reaped.
 107 **/
 108 void (*CatchChildLeaveStatus(void))(int);
 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   save a lump of data into a file. Mostly used for debugging
 337 */
 338 _PUBLIC_ bool file_save(const char *fname, const void *packet, size_t length);
 339 _PUBLIC_ int vfdprintf(int fd, const char *format, va_list ap) PRINTF_ATTRIBUTE(2,0);
 340 _PUBLIC_ int fdprintf(int fd, const char *format, ...) PRINTF_ATTRIBUTE(2,3);
 341
 342 /* The following definitions come from lib/util/util.c  */
 343
 344
 345 /**
 346  Find a suitable temporary directory. The result should be copied immediately
 347  as it may be overwritten by a subsequent call.
 348 **/
 349 _PUBLIC_ const char *tmpdir(void);
 350
 351 /**
 352  Check if a file exists - call vfs_file_exist for samba files.
 353 **/
 354 _PUBLIC_ bool file_exist(const char *fname);
 355
 356 /**
 357  Check a files mod time.
 358 **/
 359 _PUBLIC_ time_t file_modtime(const char *fname);
 360
 361 /**
 362  Check if a directory exists.
 363 **/
 364 _PUBLIC_ bool directory_exist(const char *dname);
 365
 366 /**
 367  * Try to create the specified directory if it didn't exist.
 368  *
 369  * @retval true if the directory already existed and has the right permissions
 370  * or was successfully created.
 371  */
 372 _PUBLIC_ bool directory_create_or_exist(const char *dname, uid_t uid,
 373                                mode_t dir_perms);
 374
 375 /**
 376  Set a fd into blocking/nonblocking mode. Uses POSIX O_NONBLOCK if available,
 377  else
 378   if SYSV use O_NDELAY
 379   if BSD use FNDELAY
 380 **/
 381 _PUBLIC_ int set_blocking(int fd, bool set);
 382
 383 /**
 384  Sleep for a specified number of milliseconds.
 385 **/
 386 _PUBLIC_ void msleep(unsigned int t);
 387
 388 /**
 389  Get my own name, return in malloc'ed storage.
 390 **/
 391 _PUBLIC_ char* get_myname(void);
 392
 393 /**
 394  Return true if a string could be a pure IP address.
 395 **/
 396 _PUBLIC_ bool is_ipaddress(const char *str);
 397
 398 /**
 399  Interpret an internet address or name into an IP address in 4 byte form.
 400 **/
 401 _PUBLIC_ uint32_t interpret_addr(const char *str);
 402
 403 /**
 404  A convenient addition to interpret_addr().
 405 **/
 406 _PUBLIC_ struct in_addr interpret_addr2(const char *str);
 407
 408 /**
 409  Check if an IP is the 0.0.0.0.
 410 **/
 411 _PUBLIC_ bool is_zero_ip_v4(struct in_addr ip);
 412
 413 /**
 414  Are two IPs on the same subnet?
 415 **/
 416 _PUBLIC_ bool same_net_v4(struct in_addr ip1,struct in_addr ip2,struct in_addr mask);
 417
 418 _PUBLIC_ bool is_ipaddress_v4(const char *str);
 419
 420 /**
 421  Check if a process exists. Does this work on all unixes?
 422 **/
 423 _PUBLIC_ bool process_exists_by_pid(pid_t pid);
 424
 425 /**
 426  Simple routine to do POSIX file locking. Cruft in NFS and 64->32 bit mapping
 427  is dealt with in posix.c
 428 **/
 429 _PUBLIC_ bool fcntl_lock(int fd, int op, off_t offset, off_t count, int type);
 430
 431 /**
 432  malloc that aborts with smb_panic on fail or zero size.
 433 **/
 434 _PUBLIC_ void *smb_xmalloc(size_t size);
 435
 436 /**
 437  Memdup with smb_panic on fail.
 438 **/
 439 _PUBLIC_ void *smb_xmemdup(const void *p, size_t size);
 440
 441 /**
 442  strdup that aborts on malloc fail.
 443 **/
 444 _PUBLIC_ char *smb_xstrdup(const char *s);
 445
 446 char *smb_xstrndup(const char *s, size_t n);
 447
 448 /**
 449  Like strdup but for memory.
 450 **/
 451 _PUBLIC_ void *smb_memdup(const void *p, size_t size);
 452
 453 /**
 454  * see if a range of memory is all zero. A NULL pointer is considered
 455  * to be all zero
 456  */
 457 _PUBLIC_ bool all_zero(const uint8_t *ptr, size_t size);
 458
 459 /**
 460   realloc an array, checking for integer overflow in the array size
 461 */
 462 _PUBLIC_ void *realloc_array(void *ptr, size_t el_size, unsigned count, bool free_on_fail);
 463
 464 void *malloc_array(size_t el_size, unsigned int count);
 465
 466 /* The following definitions come from lib/util/fsusage.c  */
 467
 468
 469 /**
 470  * Retrieve amount of free disk space.
 471  * this does all of the system specific guff to get the free disk space.
 472  * It is derived from code in the GNU fileutils package, but has been
 473  * considerably mangled for use here
 474  *
 475  * results are returned in *dfree and *dsize, in 512 byte units
 476 */
 477 _PUBLIC_ int sys_fsusage(const char *path, uint64_t *dfree, uint64_t *dsize);
 478
 479 /* The following definitions come from lib/util/ms_fnmatch.c  */
 480
 481
 482 /**
 483  * @file
 484  * @brief MS-style Filename matching
 485  */
 486
 487 #if _SAMBA_BUILD_ == 4
 488 #include "libcli/smb/smb_constants.h"
 489
 490 int ms_fnmatch(const char *pattern, const char *string, enum protocol_types protocol);
 491
 492 /** a generic fnmatch function - uses for non-CIFS pattern matching */
 493 int gen_fnmatch(const char *pattern, const char *string);
 494 #endif
 495
 496 /* The following definitions come from lib/util/mutex.c  */
 497
 498
 499 #ifdef _SAMBA_BUILD_
 500 /**
 501   register a set of mutex/rwlock handlers.
 502   Should only be called once in the execution of smbd.
 503 */
 504 _PUBLIC_ bool register_mutex_handlers(const char *name, struct mutex_ops *ops);
 505 #endif
 506
 507 /* The following definitions come from lib/util/idtree.c  */
 508
 509
 510 /**
 511   initialise a idr tree. The context return value must be passed to
 512   all subsequent idr calls. To destroy the idr tree use talloc_free()
 513   on this context
 514  */
 515 _PUBLIC_ struct idr_context *idr_init(TALLOC_CTX *mem_ctx);
 516
 517 /**
 518   allocate the next available id, and assign 'ptr' into its slot.
 519   you can retrieve later this pointer using idr_find()
 520 */
 521 _PUBLIC_ int idr_get_new(struct idr_context *idp, void *ptr, int limit);
 522
 523 /**
 524    allocate a new id, giving the first available value greater than or
 525    equal to the given starting id
 526 */
 527 _PUBLIC_ int idr_get_new_above(struct idr_context *idp, void *ptr, int starting_id, int limit);
 528
 529 /**
 530   allocate a new id randomly in the given range
 531 */
 532 _PUBLIC_ int idr_get_new_random(struct idr_context *idp, void *ptr, int limit);
 533
 534 /**
 535   find a pointer value previously set with idr_get_new given an id
 536 */
 537 _PUBLIC_ void *idr_find(struct idr_context *idp, int id);
 538
 539 /**
 540   remove an id from the idr tree
 541 */
 542 _PUBLIC_ int idr_remove(struct idr_context *idp, int id);
 543
 544 /* The following definitions come from lib/util/become_daemon.c  */
 545
 546 #if _SAMBA_BUILD_ == 4
 547 /**
 548  Become a daemon, discarding the controlling terminal.
 549 **/
 550 _PUBLIC_ void become_daemon(bool fork);
 551 #endif
 552
 553 /**
 554  * Load a ini-style file.
 555  */
 556 bool pm_process( const char *fileName,
 557                  bool (*sfunc)(const char *, void *),
 558                  bool (*pfunc)(const char *, const char *, void *),
 559                                  void *userdata);
 560
 561 bool unmap_file(void *start, size_t size);
 562
 563 #define CONST_DISCARD(type, ptr)      ((type) ((void *) (ptr)))
 564
 565 #endif /* _SAMBA_UTIL_H_ */