source/lib/util/README

   1 This directory contains convenience functions that are used heavily
   2 throughout Samba.  None of these functions are SMB or Samba-specific.
   3 It's a bit to Samba what GLib is to the GNOME folks.
   4
   5 (This file should be migrated to doxygen sometime.. )
   6
   7 Also TODO: Remove dependency on loadparm
   8
   9 XFILE wrapper functions
  10 =======================
  11 The XFILE implementation contains a clone of the standard UNIX stdio
  12 functions
  13
  14 Debug functions
  15 ===============
  16 DEBUG()
  17
  18 Crash handlers
  19 ==============
  20 void smb_panic(const char *why);
  21
  22 Signal handling
  23 ========================
  24 void BlockSignals(BOOL block,int signum);
  25 void (*CatchSignal(int signum,void (*handler)(int )))(int);
  26 void CatchChild(void);
  27 void CatchChildLeaveStatus(void);
  28
  29 Wrappers
  30 ========
  31 struct hostent *sys_gethostbyname(const char *name);
  32 const char *sys_inet_ntoa(struct ipv4_addr in);
  33 struct ipv4_addr sys_inet_makeaddr(int net, int host);
  34 void sys_select_signal(void);
  35 int sys_select(int maxfd, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval *tval);
  36 int sys_select_intr(int maxfd, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval *tval);
  37
  38 Time datastructures
  39 ===================
  40 time_t get_time_t_max(void);
  41 void GetTimeOfDay(struct timeval *tval);
  42 time_t nt_time_to_unix(NTTIME nt);
  43 void unix_to_nt_time(NTTIME *nt, time_t t);
  44 BOOL null_time(time_t t);
  45 BOOL null_nttime(NTTIME t);
  46 void push_dos_date(uint8_t *buf, int offset, time_t unixdate, int zone_offset);
  47 void push_dos_date2(uint8_t *buf,int offset,time_t unixdate, int zone_offset);
  48 void push_dos_date3(uint8_t *buf,int offset,time_t unixdate, int zone_offset);
  49 time_t pull_dos_date(const uint8_t *date_ptr, int zone_offset);
  50 time_t pull_dos_date2(const uint8_t *date_ptr, int zone_offset);
  51 time_t pull_dos_date3(const uint8_t *date_ptr, int zone_offset);
  52 char *http_timestring(TALLOC_CTX *mem_ctx, time_t t);
  53 char *timestring(TALLOC_CTX *mem_ctx, time_t t);
  54 const char *nt_time_string(TALLOC_CTX *mem_ctx, NTTIME nt);
  55 void push_nttime(uint8_t *base, uint16_t offset, NTTIME t);
  56 NTTIME pull_nttime(uint8_t *base, uint16_t offset);
  57 NTTIME nttime_from_string(const char *s);
  58 int64_t usec_time_diff(struct timeval *tv1, struct timeval *tv2);
  59 struct timeval timeval_zero(void);
  60 BOOL timeval_is_zero(const struct timeval *tv);
  61 struct timeval timeval_current(void);
  62 struct timeval timeval_set(uint32_t secs, uint32_t usecs);
  63 struct timeval timeval_add(const struct timeval *tv,
  64                            uint32_t secs, uint32_t usecs);
  65 struct timeval timeval_sum(const struct timeval *tv1,
  66                            const struct timeval *tv2);
  67 struct timeval timeval_current_ofs(uint32_t secs, uint32_t usecs);
  68 int timeval_compare(const struct timeval *tv1, const struct timeval *tv2);
  69 BOOL timeval_expired(const struct timeval *tv);
  70 double timeval_elapsed2(const struct timeval *tv1, const struct timeval *tv2);
  71 double timeval_elapsed(const struct timeval *tv);
  72 struct timeval timeval_min(const struct timeval *tv1,
  73                            const struct timeval *tv2);
  74 struct timeval timeval_max(const struct timeval *tv1,
  75                            const struct timeval *tv2);
  76 struct timeval timeval_until(const struct timeval *tv1,
  77                              const struct timeval *tv2);
  78 NTTIME timeval_to_nttime(const struct timeval *tv);
  79 int get_time_zone(time_t t);
  80
  81 Random number generation
  82 ========================
  83 void set_rand_reseed_callback(void (*fn)(int *));
  84 void set_need_random_reseed(void);
  85 void generate_random_buffer(uint8_t *out, int len);
  86 uint32_t generate_random(void);
  87 BOOL check_password_quality(const char *s);
  88 char *generate_random_str_list(TALLOC_CTX *mem_ctx, size_t len, const char *list);
  89 char *generate_random_str(TALLOC_CTX *mem_ctx, size_t len);
  90
  91 String manipulation
  92 ===================
  93 BOOL next_token(const char **ptr,char *buff, const char *sep, size_t bufsize);
  94 int strcasecmp_m(const char *s1, const char *s2);
  95 BOOL strequal(const char *s1, const char *s2);
  96 BOOL strcsequal(const char *s1,const char *s2);
  97 int strwicmp(const char *psz1, const char *psz2);
  98 void string_replace(char *s, char oldc, char newc);
  99 BOOL trim_string(char *s,const char *front,const char *back);
 100 size_t count_chars(const char *s, char c);
 101 char *safe_strcpy(char *dest,const char *src, size_t maxlength);
 102 char *safe_strcat(char *dest, const char *src, size_t maxlength);
 103 char *alpha_strcpy(char *dest, const char *src, const char *other_safe_chars, size_t maxlength);
 104 char *StrnCpy(char *dest,const char *src,size_t n);
 105 size_t strhex_to_str(char *p, size_t len, const char *strhex);
 106 DATA_BLOB strhex_to_data_blob(const char *strhex) ;
 107 void hex_encode(const unsigned char *buff_in, size_t len, char **out_hex_buffer);
 108 BOOL in_list(const char *s, const char *list, BOOL casesensitive);
 109 void string_free(char **s);
 110 BOOL string_set(char **dest, const char *src);
 111 void string_sub(char *s,const char *pattern, const char *insert, size_t len);
 112 void all_string_sub(char *s,const char *pattern,const char *insert, size_t len);
 113 char *strchr_m(const char *s, char c);
 114 char *strrchr_m(const char *s, char c);
 115 BOOL strhaslower(const char *string);
 116 BOOL strhasupper(const char *string);
 117 char *strlower_talloc(TALLOC_CTX *ctx, const char *src);
 118 char *strupper_talloc(TALLOC_CTX *ctx, const char *src);
 119 void strlower_m(char *s);
 120 void strupper_m(char *s);
 121 size_t strlen_m(const char *s);
 122 size_t strlen_m_term(const char *s);
 123 void rfc1738_unescape(char *buf);
 124 DATA_BLOB base64_decode_data_blob(TALLOC_CTX *mem_ctx, const char *s);
 125 void base64_decode_inplace(char *s);
 126 char *base64_encode_data_blob(TALLOC_CTX *mem_ctx, DATA_BLOB data);
 127 size_t valgrind_strlen(const char *s);
 128 const char *str_format_nbt_domain(TALLOC_CTX *mem_ctx, const char *s);
 129 BOOL add_string_to_array(TALLOC_CTX *mem_ctx,
 130                          const char *str, const char ***strings, int *num);
 131 int strcmp_safe(const char *s1, const char *s2);
 132 size_t ascii_len_n(const char *src, size_t n);
 133 char *attrib_string(TALLOC_CTX *mem_ctx, uint32_t attrib);
 134 BOOL set_boolean(const char *boolean_string, BOOL *boolean);
 135 BOOL conv_str_bool(const char * str, BOOL * val);
 136 BOOL conv_str_size(const char * str, uint64_t * val);
 137 BOOL conv_str_u64(const char * str, uint64_t * val);
 138
 139 String list manipulation
 140 ========================
 141 const char **str_list_make(TALLOC_CTX *mem_ctx, const char *string, const char *sep);
 142 const char **str_list_make_shell(TALLOC_CTX *mem_ctx, const char *string, const char *sep);
 143 char *str_list_join(TALLOC_CTX *mem_ctx, const char **list, char seperator);
 144 char *str_list_join_shell(TALLOC_CTX *mem_ctx, const char **list, char sep);
 145 size_t str_list_length(const char **list);
 146 const char **str_list_copy(TALLOC_CTX *mem_ctx, const char **list);
 147 BOOL str_list_equal(const char **list1, const char **list2);
 148 const char **str_list_add(const char **list, const char *s);
 149 void str_list_remove(const char **list, const char *s);
 150 BOOL str_list_check(const char **list, const char *s);
 151 BOOL str_list_check_ci(const char **list, const char *s);
 152
 153 Unicode string manipulation
 154 ===========================
 155 codepoint_t toupper_w(codepoint_t val);
 156 codepoint_t tolower_w(codepoint_t val);
 157 size_t utf16_len(const void *buf);
 158 size_t utf16_len_n(const void *src, size_t n);
 159 size_t ucs2_align(const void *base_ptr, const void *p, int flags);
 160 int codepoint_cmpi(codepoint_t c1, codepoint_t c2);
 161
 162 File manipulation
 163 =================
 164 char *fgets_slash(char *s2,int maxlen,XFILE *f);
 165 char *afdgets(int fd, TALLOC_CTX *mem_ctx, size_t hint);
 166 char *fd_load(int fd, size_t *size, TALLOC_CTX *mem_ctx);
 167 char *file_load(const char *fname, size_t *size, TALLOC_CTX *mem_ctx);
 168 void *map_file(const char *fname, size_t size);
 169 char **file_lines_load(const char *fname, int *numlines, TALLOC_CTX *mem_ctx);
 170 char **fd_lines_load(int fd, int *numlines, TALLOC_CTX *mem_ctx);
 171 void file_lines_slashcont(char **lines);
 172 BOOL file_save(const char *fname, const void *packet, size_t length);
 173 BOOL file_exists(const char *path);
 174 int vfdprintf(int fd, const char *format, va_list ap) _PRINTF_ATTRIBUTE(2,0);
 175 int fdprintf(int fd, const char *format, ...) _PRINTF_ATTRIBUTE(2,3);
 176
 177 Data Blob
 178 =========
 179 DATA_BLOB data_blob_named(const void *p, size_t length, const char *name);
 180 DATA_BLOB data_blob_talloc_named(TALLOC_CTX *mem_ctx, const void *p, size_t length, const char *name);
 181 DATA_BLOB data_blob_talloc_reference(TALLOC_CTX *mem_ctx, DATA_BLOB *blob);
 182 DATA_BLOB data_blob_talloc_zero(TALLOC_CTX *mem_ctx, size_t length);
 183 void data_blob_free(DATA_BLOB *d);
 184 void data_blob_clear(DATA_BLOB *d);
 185 void data_blob_clear_free(DATA_BLOB *d);
 186 BOOL data_blob_equal(const DATA_BLOB *d1, const DATA_BLOB *d2);
 187 char *data_blob_hex_string(TALLOC_CTX *mem_ctx, DATA_BLOB *blob);
 188 DATA_BLOB data_blob_string_const(const char *str);
 189 DATA_BLOB data_blob_const(const void *p, size_t length);
 190 NTSTATUS data_blob_realloc(TALLOC_CTX *mem_ctx, DATA_BLOB *blob, size_t length);
 191 NTSTATUS data_blob_append(TALLOC_CTX *mem_ctx, DATA_BLOB *blob,
 192                           const void *p, size_t length);
 193
 194 Random Utility functions
 195 ========================
 196 const char *tmpdir(void);
 197 BOOL file_exist(const char *fname);
 198 time_t file_modtime(const char *fname);
 199 BOOL directory_exist(const char *dname);
 200 BOOL directory_create_or_exist(const char *dname, uid_t uid,
 201                                mode_t dir_perms);
 202 int set_blocking(int fd, BOOL set);
 203 void msleep(uint_t t);
 204 void become_daemon(BOOL Fork);
 205 void safe_free(void *p);
 206 BOOL is_myname(const char *name);
 207 char* get_myname(void);
 208 BOOL is_ipaddress(const char *str);
 209 uint32_t interpret_addr(const char *str);
 210 struct ipv4_addr interpret_addr2(const char *str);
 211 BOOL is_zero_ip(struct ipv4_addr ip);
 212 BOOL same_net(struct ipv4_addr ip1,struct ipv4_addr ip2,struct ipv4_addr mask);
 213 BOOL process_exists(pid_t pid);
 214 BOOL fcntl_lock(int fd, int op, off_t offset, off_t count, int type);
 215 void dump_data(int level, const uint8_t *buf,int len);
 216 void *smb_xmalloc(size_t size);
 217 void *smb_xmemdup(const void *p, size_t size);
 218 char *smb_xstrdup(const char *s);
 219 void *memdup(const void *p, size_t size);
 220 char *lock_path(TALLOC_CTX* mem_ctx, const char *name);
 221 char *lib_path(TALLOC_CTX* mem_ctx, const char *name);
 222 char *private_path(TALLOC_CTX* mem_ctx, const char *name);
 223 char *smbd_tmp_path(TALLOC_CTX *mem_ctx, const char *name);
 224 init_module_fn *load_samba_modules(TALLOC_CTX *mem_ctx, const char *subsystem);
 225 void dump_data_pw(const char *msg, const uint8_t * data, size_t len);
 226 BOOL all_zero(const uint8_t *ptr, uint_t size);
 227 void *realloc_array(void *ptr, size_t el_size, unsigned count);
 228
 229 /* The following definitions come from lib/util/util_sock.c  */
 230
 231 void set_socket_options(int fd, const char *options);
 232
 233 Variable substitution
 234 =====================
 235 void sub_set_context(struct substitute_context *subptr);
 236 void sub_set_remote_proto(const char *str);
 237 void sub_set_remote_arch(const char *str);
 238 void sub_set_user_name(const char *name);
 239 void standard_sub_basic(char *str,size_t len);
 240 char *talloc_sub_basic(TALLOC_CTX *mem_ctx, const char *smb_name, const char *str);
 241 char *alloc_sub_basic(const char *smb_name, const char *str);
 242 char *talloc_sub_specified(TALLOC_CTX *mem_ctx,
 243                         const char *input_string,
 244                         const char *username,
 245                         const char *domain,
 246                         uid_t uid,
 247                         gid_t gid);
 248 char *alloc_sub_specified(const char *input_string,
 249                         const char *username,
 250                         const char *domain,
 251                         uid_t uid,
 252                         gid_t gid);
 253 char *talloc_sub_advanced(TALLOC_CTX *mem_ctx,
 254                         int snum,
 255                         const char *user,
 256                         const char *connectpath,
 257                         gid_t gid,
 258                         const char *smb_name,
 259                         char *str);
 260 char *alloc_sub_advanced(int snum, const char *user,
 261                                   const char *connectpath, gid_t gid,
 262                                   const char *smb_name, char *str);
 263 void standard_sub_tcon(struct smbsrv_tcon *tcon, char *str, size_t len);
 264 char *talloc_sub_tcon(TALLOC_CTX *mem_ctx, struct smbsrv_tcon *tcon, char *str);
 265 char *alloc_sub_tcon(struct smbsrv_tcon *tcon, char *str);
 266 void standard_sub_snum(int snum, char *str, size_t len);
 267
 268 /* The following definitions come from lib/util/fsusage.c  */
 269
 270 int sys_fsusage(const char *path, uint64_t *dfree, uint64_t *dsize);
 271
 272 Microsoft-style filename matching
 273 =================================
 274 int ms_fnmatch(const char *pattern, const char *string, enum protocol_types protocol);
 275 int gen_fnmatch(const char *pattern, const char *string);
 276
 277 Mutexes
 278 =======
 279 BOOL register_mutex_handlers(const char *name, struct mutex_ops *ops);
 280
 281 Idtree
 282 ======
 283 very efficient functions to manage mapping a id (such as a fnum) to
 284 a pointer. This is used for fnum and search id allocation.
 285
 286 struct idr_context *idr_init(TALLOC_CTX *mem_ctx);
 287 int idr_get_new(struct idr_context *idp, void *ptr, int limit);
 288 int idr_get_new_above(struct idr_context *idp, void *ptr, int starting_id, int limit);
 289 int idr_get_new_random(struct idr_context *idp, void *ptr, int limit);
 290 void *idr_find(struct idr_context *idp, int id);
 291 int idr_remove(struct idr_context *idp, int id);
 292
 293 Module loading
 294 ==============
 295 init_module_fn *load_modules(TALLOC_CTX *mem_ctx, const char *path);
 296 BOOL run_init_functions(NTSTATUS (**fns) (void));