r13849: More improvements to the libutil docs.

(This used to be commit eed16ac3b7f7062a34f09f602db0f828cac7f246)

3 files changed, 68 insertions, 302 deletions

diff --git a/source4/lib/util/README b/source4/lib/util/README
deleted file mode 100644
index e52e04ed92..0000000000
--- a/source4/lib/util/README
+++ /dev/null
@@ -1,296 +0,0 @@
-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));
diff --git a/source4/lib/util/mainpage.dox b/source4/lib/util/mainpage.dox
new file mode 100644
index 0000000000..464151e771
--- /dev/null
+++ b/source4/lib/util/mainpage.dox
@@ -0,0 +1,11 @@
+/**
+
+\mainpage util
+
+\section Introduction
+
+This library 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.
+
+*/
diff --git a/source4/lib/util/util.h b/source4/lib/util/util.h
index 55d775e25c..272cc13f4e 100644
--- a/source4/lib/util/util.h
+++ b/source4/lib/util/util.h
@@ -24,6 +24,11 @@
 #ifndef _SAMBA_UTIL_H_
 #define _SAMBA_UTIL_H_
 
+/**
+ * @file
+ * @brief Helpful macros
+ */
+
 struct substitute_context;
 
 #include "util/xfile.h"
@@ -32,34 +37,55 @@ struct substitute_context;
 #include "util/byteorder.h"
 #include "util/util_proto.h"
 
-/* zero a structure */
+/** 
+ * zero a structure 
+ */
 #define ZERO_STRUCT(x) memset((char *)&(x), 0, sizeof(x))
 
-/* zero a structure given a pointer to the structure */
+/** 
+ * zero a structure given a pointer to the structure 
+ */
 #define ZERO_STRUCTP(x) do { if ((x) != NULL) memset((char *)(x), 0, sizeof(*(x))); } while(0)
 
-/* zero a structure given a pointer to the structure - no zero check */
+/** 
+ * zero a structure given a pointer to the structure - no zero check 
+ */
 #define ZERO_STRUCTPN(x) memset((char *)(x), 0, sizeof(*(x)))
 
-/* pointer difference macro */
+/** 
+ * pointer difference macro 
+ */
 #define PTR_DIFF(p1,p2) ((ptrdiff_t)(((const char *)(p1)) - (const char *)(p2)))
 
-/* work out how many elements there are in a static array */
+/**
+ * work out how many elements there are in a static array 
+ */
 #define ARRAY_SIZE(a) (sizeof(a)/sizeof(a[0]))
 
-/* assert macros */
+/**
+ * assert macros 
+ */
 #define SMB_ASSERT(b) do { if (!(b)) { \
 	DEBUG(0,("PANIC: assert failed at %s(%d)\n", __FILE__, __LINE__)); \
 	smb_panic("assert failed"); }} while (0)
 
+/**
+ * determine the lowest of two values
+ */
 #ifndef MIN
 #define MIN(a,b) ((a)<(b)?(a):(b))
 #endif
 
+/**
+ * determine the highest of two values
+ */
 #ifndef MAX
 #define MAX(a,b) ((a)>(b)?(a):(b))
 #endif
 
+/**
+ * determine absolute value
+ */
 #ifndef ABS
 #define ABS(a) ((a)>0?(a):(-(a)))
 #endif
@@ -78,4 +104,29 @@ struct substitute_context;
 #define malloc_array_p(type, count) (type *)realloc_array(NULL, sizeof(type), count)
 #define realloc_p(p, type, count) (type *)realloc_array(p, sizeof(type), count)
 
+#if defined(VALGRIND)
+#define strlen(x) valgrind_strlen(x)
+#endif
+
+/**
+  this is a warning hack. The idea is to use this everywhere that we
+  get the "discarding const" warning from gcc. That doesn't actually
+  fix the problem of course, but it means that when we do get to
+  cleaning them up we can do it by searching the code for
+  discard_const.
+
+  It also means that other error types aren't as swamped by the noise
+  of hundreds of const warnings, so we are more likely to notice when
+  we get new errors.
+
+  Please only add more uses of this macro when you find it
+  _really_ hard to fix const warnings. Our aim is to eventually use
+  this function in only a very few places.
+
+  Also, please call this via the discard_const_p() macro interface, as that
+  makes the return type safe.
+*/
+#define discard_const(ptr) ((void *)((intptr_t)(ptr)))
+#define discard_const_p(type, ptr) ((type *)discard_const(ptr))
+
 #endif /* _SAMBA_UTIL_H_ */