path: root/source4/lib/util/README

This directory contains convenience functions that are used heavily 
throughout Samba.  None of these functions are SMB or Samba-specific.
It's a bit to Samba what GLib is to the GNOME folks.

(This file should be migrated to doxygen sometime.. )

Also TODO: Remove dependency on loadparm

XFILE wrapper functions
=======================
The XFILE implementation contains a clone of the standard UNIX stdio 
functions 

Debug functions
===============
DEBUG()

Crash handlers
==============
void smb_panic(const char *why);

Signal handling
========================
void BlockSignals(BOOL block,int signum);
void (*CatchSignal(int signum,void (*handler)(int )))(int);
void CatchChild(void);
void CatchChildLeaveStatus(void);

Wrappers
========
struct hostent *sys_gethostbyname(const char *name);
const char *sys_inet_ntoa(struct ipv4_addr in);
struct ipv4_addr sys_inet_makeaddr(int net, int host);
void sys_select_signal(void);
int sys_select(int maxfd, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval *tval);
int sys_select_intr(int maxfd, fd_set *readfds, fd_set *writefds, fd_set *errorfds, struct timeval *tval);

Time datastructures
===================
time_t get_time_t_max(void);
void GetTimeOfDay(struct timeval *tval);
time_t nt_time_to_unix(NTTIME nt);
void unix_to_nt_time(NTTIME *nt, time_t t);
BOOL null_time(time_t t);
BOOL null_nttime(NTTIME t);
void push_dos_date(uint8_t *buf, int offset, time_t unixdate, int zone_offset);
void push_dos_date2(uint8_t *buf,int offset,time_t unixdate, int zone_offset);
void push_dos_date3(uint8_t *buf,int offset,time_t unixdate, int zone_offset);
time_t pull_dos_date(const uint8_t *date_ptr, int zone_offset);
time_t pull_dos_date2(const uint8_t *date_ptr, int zone_offset);
time_t pull_dos_date3(const uint8_t *date_ptr, int zone_offset);
char *http_timestring(TALLOC_CTX *mem_ctx, time_t t);
char *timestring(TALLOC_CTX *mem_ctx, time_t t);
const char *nt_time_string(TALLOC_CTX *mem_ctx, NTTIME nt);
void push_nttime(uint8_t *base, uint16_t offset, NTTIME t);
NTTIME pull_nttime(uint8_t *base, uint16_t offset);
NTTIME nttime_from_string(const char *s);
int64_t usec_time_diff(struct timeval *tv1, struct timeval *tv2);
struct timeval timeval_zero(void);
BOOL timeval_is_zero(const struct timeval *tv);
struct timeval timeval_current(void);
struct timeval timeval_set(uint32_t secs, uint32_t usecs);
struct timeval timeval_add(const struct timeval *tv,
			   uint32_t secs, uint32_t usecs);
struct timeval timeval_sum(const struct timeval *tv1,
			   const struct timeval *tv2);
struct timeval timeval_current_ofs(uint32_t secs, uint32_t usecs);
int timeval_compare(const struct timeval *tv1, const struct timeval *tv2);
BOOL timeval_expired(const struct timeval *tv);
double timeval_elapsed2(const struct timeval *tv1, const struct timeval *tv2);
double timeval_elapsed(const struct timeval *tv);
struct timeval timeval_min(const struct timeval *tv1,
			   const struct timeval *tv2);
struct timeval timeval_max(const struct timeval *tv1,
			   const struct timeval *tv2);
struct timeval timeval_until(const struct timeval *tv1,
			     const struct timeval *tv2);
NTTIME timeval_to_nttime(const struct timeval *tv);
int get_time_zone(time_t t);

Random number generation
========================
void set_rand_reseed_callback(void (*fn)(int *));
void set_need_random_reseed(void);
void generate_random_buffer(uint8_t *out, int len);
uint32_t generate_random(void);
BOOL check_password_quality(const char *s);
char *generate_random_str_list(TALLOC_CTX *mem_ctx, size_t len, const char *list);
char *generate_random_str(TALLOC_CTX *mem_ctx, size_t len);

String manipulation
===================
BOOL next_token(const char **ptr,char *buff, const char *sep, size_t bufsize);
int strcasecmp_m(const char *s1, const char *s2);
BOOL strequal(const char *s1, const char *s2);
BOOL strcsequal(const char *s1,const char *s2);
int strwicmp(const char *psz1, const char *psz2);
void string_replace(char *s, char oldc, char newc);
BOOL trim_string(char *s,const char *front,const char *back);
size_t count_chars(const char *s, char c);
char *safe_strcpy(char *dest,const char *src, size_t maxlength);
char *safe_strcat(char *dest, const char *src, size_t maxlength);
char *alpha_strcpy(char *dest, const char *src, const char *other_safe_chars, size_t maxlength);
char *StrnCpy(char *dest,const char *src,size_t n);
size_t strhex_to_str(char *p, size_t len, const char *strhex);
DATA_BLOB strhex_to_data_blob(const char *strhex) ;
void hex_encode(const unsigned char *buff_in, size_t len, char **out_hex_buffer);
BOOL in_list(const char *s, const char *list, BOOL casesensitive);
void string_free(char **s);
BOOL string_set(char **dest, const char *src);
void string_sub(char *s,const char *pattern, const char *insert, size_t len);
void all_string_sub(char *s,const char *pattern,const char *insert, size_t len);
char *strchr_m(const char *s, char c);
char *strrchr_m(const char *s, char c);
BOOL strhaslower(const char *string);
BOOL strhasupper(const char *string);
char *strlower_talloc(TALLOC_CTX *ctx, const char *src);
char *strupper_talloc(TALLOC_CTX *ctx, const char *src);
void strlower_m(char *s);
void strupper_m(char *s);
size_t strlen_m(const char *s);
size_t strlen_m_term(const char *s);
void rfc1738_unescape(char *buf);
DATA_BLOB base64_decode_data_blob(TALLOC_CTX *mem_ctx, const char *s);
void base64_decode_inplace(char *s);
char *base64_encode_data_blob(TALLOC_CTX *mem_ctx, DATA_BLOB data);
size_t valgrind_strlen(const char *s);
const char *str_format_nbt_domain(TALLOC_CTX *mem_ctx, const char *s);
BOOL add_string_to_array(TALLOC_CTX *mem_ctx,
			 const char *str, const char ***strings, int *num);
int strcmp_safe(const char *s1, const char *s2);
size_t ascii_len_n(const char *src, size_t n);
char *attrib_string(TALLOC_CTX *mem_ctx, uint32_t attrib);
BOOL set_boolean(const char *boolean_string, BOOL *boolean);
BOOL conv_str_bool(const char * str, BOOL * val);
BOOL conv_str_size(const char * str, uint64_t * val);
BOOL conv_str_u64(const char * str, uint64_t * val);

String list manipulation
========================
const char **str_list_make(TALLOC_CTX *mem_ctx, const char *string, const char *sep);
const char **str_list_make_shell(TALLOC_CTX *mem_ctx, const char *string, const char *sep);
char *str_list_join(TALLOC_CTX *mem_ctx, const char **list, char seperator);
char *str_list_join_shell(TALLOC_CTX *mem_ctx, const char **list, char sep);
size_t str_list_length(const char **list);
const char **str_list_copy(TALLOC_CTX *mem_ctx, const char **list);
BOOL str_list_equal(const char **list1, const char **list2);
const char **str_list_add(const char **list, const char *s);
void str_list_remove(const char **list, const char *s);
BOOL str_list_check(const char **list, const char *s);
BOOL str_list_check_ci(const char **list, const char *s);

Unicode string manipulation
===========================
codepoint_t toupper_w(codepoint_t val);
codepoint_t tolower_w(codepoint_t val);
size_t utf16_len(const void *buf);
size_t utf16_len_n(const void *src, size_t n);
size_t ucs2_align(const void *base_ptr, const void *p, int flags);
int codepoint_cmpi(codepoint_t c1, codepoint_t c2);

File manipulation
=================
char *fgets_slash(char *s2,int maxlen,XFILE *f);
char *afdgets(int fd, TALLOC_CTX *mem_ctx, size_t hint);
char *fd_load(int fd, size_t *size, TALLOC_CTX *mem_ctx);
char *file_load(const char *fname, size_t *size, TALLOC_CTX *mem_ctx);
void *map_file(const char *fname, size_t size);
char **file_lines_load(const char *fname, int *numlines, TALLOC_CTX *mem_ctx);
char **fd_lines_load(int fd, int *numlines, TALLOC_CTX *mem_ctx);
void file_lines_slashcont(char **lines);
BOOL file_save(const char *fname, const void *packet, size_t length);
BOOL file_exists(const char *path);
int vfdprintf(int fd, const char *format, va_list ap) _PRINTF_ATTRIBUTE(2,0);
int fdprintf(int fd, const char *format, ...) _PRINTF_ATTRIBUTE(2,3);

Data Blob
=========
DATA_BLOB data_blob_named(const void *p, size_t length, const char *name);
DATA_BLOB data_blob_talloc_named(TALLOC_CTX *mem_ctx, const void *p, size_t length, const char *name);
DATA_BLOB data_blob_talloc_reference(TALLOC_CTX *mem_ctx, DATA_BLOB *blob);
DATA_BLOB data_blob_talloc_zero(TALLOC_CTX *mem_ctx, size_t length);
void data_blob_free(DATA_BLOB *d);
void data_blob_clear(DATA_BLOB *d);
void data_blob_clear_free(DATA_BLOB *d);
BOOL data_blob_equal(const DATA_BLOB *d1, const DATA_BLOB *d2);
char *data_blob_hex_string(TALLOC_CTX *mem_ctx, DATA_BLOB *blob);
DATA_BLOB data_blob_string_const(const char *str);
DATA_BLOB data_blob_const(const void *p, size_t length);
NTSTATUS data_blob_realloc(TALLOC_CTX *mem_ctx, DATA_BLOB *blob, size_t length);
NTSTATUS data_blob_append(TALLOC_CTX *mem_ctx, DATA_BLOB *blob,
			  const void *p, size_t length);

Random Utility functions
========================
const char *tmpdir(void);
BOOL file_exist(const char *fname);
time_t file_modtime(const char *fname);
BOOL directory_exist(const char *dname);
BOOL directory_create_or_exist(const char *dname, uid_t uid, 
			       mode_t dir_perms);
int set_blocking(int fd, BOOL set);
void msleep(uint_t t);
void become_daemon(BOOL Fork);
void safe_free(void *p);
BOOL is_myname(const char *name);
char* get_myname(void);
BOOL is_ipaddress(const char *str);
uint32_t interpret_addr(const char *str);
struct ipv4_addr interpret_addr2(const char *str);
BOOL is_zero_ip(struct ipv4_addr ip);
BOOL same_net(struct ipv4_addr ip1,struct ipv4_addr ip2,struct ipv4_addr mask);
BOOL process_exists(pid_t pid);
BOOL fcntl_lock(int fd, int op, off_t offset, off_t count, int type);
void dump_data(int level, const uint8_t *buf,int len);
void *smb_xmalloc(size_t size);
void *smb_xmemdup(const void *p, size_t size);
char *smb_xstrdup(const char *s);
void *memdup(const void *p, size_t size);
char *lock_path(TALLOC_CTX* mem_ctx, const char *name);
char *lib_path(TALLOC_CTX* mem_ctx, const char *name);
char *private_path(TALLOC_CTX* mem_ctx, const char *name);
char *smbd_tmp_path(TALLOC_CTX *mem_ctx, const char *name);
init_module_fn *load_samba_modules(TALLOC_CTX *mem_ctx, const char *subsystem);
void dump_data_pw(const char *msg, const uint8_t * data, size_t len);
BOOL all_zero(const uint8_t *ptr, uint_t size);
void *realloc_array(void *ptr, size_t el_size, unsigned count);

/* The following definitions come from lib/util/util_sock.c  */

void set_socket_options(int fd, const char *options);

Variable substitution
=====================
void sub_set_context(struct substitute_context *subptr);
void sub_set_remote_proto(const char *str);
void sub_set_remote_arch(const char *str);
void sub_set_user_name(const char *name);
void standard_sub_basic(char *str,size_t len);
char *talloc_sub_basic(TALLOC_CTX *mem_ctx, const char *smb_name, const char *str);
char *alloc_sub_basic(const char *smb_name, const char *str);
char *talloc_sub_specified(TALLOC_CTX *mem_ctx,
			const char *input_string,
			const char *username,
			const char *domain,
			uid_t uid,
			gid_t gid);
char *alloc_sub_specified(const char *input_string,
			const char *username,
			const char *domain,
			uid_t uid,
			gid_t gid);
char *talloc_sub_advanced(TALLOC_CTX *mem_ctx,
			int snum,
			const char *user,
			const char *connectpath,
			gid_t gid,
			const char *smb_name,
			char *str);
char *alloc_sub_advanced(int snum, const char *user, 
				  const char *connectpath, gid_t gid, 
				  const char *smb_name, char *str);
void standard_sub_tcon(struct smbsrv_tcon *tcon, char *str, size_t len);
char *talloc_sub_tcon(TALLOC_CTX *mem_ctx, struct smbsrv_tcon *tcon, char *str);
char *alloc_sub_tcon(struct smbsrv_tcon *tcon, char *str);
void standard_sub_snum(int snum, char *str, size_t len);

/* The following definitions come from lib/util/fsusage.c  */

int sys_fsusage(const char *path, uint64_t *dfree, uint64_t *dsize);

Microsoft-style filename matching
=================================
int ms_fnmatch(const char *pattern, const char *string, enum protocol_types protocol);
int gen_fnmatch(const char *pattern, const char *string);

Mutexes
=======
BOOL register_mutex_handlers(const char *name, struct mutex_ops *ops);

Idtree
======
very efficient functions to manage mapping a id (such as a fnum) to
a pointer. This is used for fnum and search id allocation.

struct idr_context *idr_init(TALLOC_CTX *mem_ctx);
int idr_get_new(struct idr_context *idp, void *ptr, int limit);
int idr_get_new_above(struct idr_context *idp, void *ptr, int starting_id, int limit);
int idr_get_new_random(struct idr_context *idp, void *ptr, int limit);
void *idr_find(struct idr_context *idp, int id);
int idr_remove(struct idr_context *idp, int id);

Module loading
==============
init_module_fn *load_modules(TALLOC_CTX *mem_ctx, const char *path);
BOOL run_init_functions(NTSTATUS (**fns) (void));