diff options
Diffstat (limited to 'source4/lib/util/README')
| -rw-r--r-- | source4/lib/util/README | 296 |
1 files changed, 296 insertions, 0 deletions
diff --git a/source4/lib/util/README b/source4/lib/util/README new file mode 100644 index 0000000000..e52e04ed92 --- /dev/null +++ b/source4/lib/util/README @@ -0,0 +1,296 @@ +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)); |