summaryrefslogtreecommitdiff
path: root/source4/lib
diff options
context:
space:
mode:
Diffstat (limited to 'source4/lib')
-rw-r--r--source4/lib/util/capability.c4
-rw-r--r--source4/lib/util/data_blob.c4
-rw-r--r--source4/lib/util/debug.c12
-rw-r--r--source4/lib/util/debug.h20
-rw-r--r--source4/lib/util/genrand.c10
-rw-r--r--source4/lib/util/mutex.h5
-rw-r--r--source4/lib/util/unix_privs.c6
-rw-r--r--source4/lib/util/util.c23
-rw-r--r--source4/lib/util/util.h14
-rw-r--r--source4/lib/util/util_str.c30
-rw-r--r--source4/lib/util/xfile.c31
11 files changed, 134 insertions, 25 deletions
diff --git a/source4/lib/util/capability.c b/source4/lib/util/capability.c
index 0062bb5cd6..09af293087 100644
--- a/source4/lib/util/capability.c
+++ b/source4/lib/util/capability.c
@@ -103,9 +103,9 @@ static BOOL set_inherited_process_capability( uint32_t cap_flag, BOOL enable )
}
#endif
-/****************************************************************************
+/**
Gain the oplock capability from the kernel if possible.
-****************************************************************************/
+**/
_PUBLIC_ void oplock_set_capability(BOOL this_process, BOOL inherit)
{
diff --git a/source4/lib/util/data_blob.c b/source4/lib/util/data_blob.c
index c1513a1d78..ac6589aa50 100644
--- a/source4/lib/util/data_blob.c
+++ b/source4/lib/util/data_blob.c
@@ -178,6 +178,10 @@ _PUBLIC_ DATA_BLOB data_blob_string_const(const char *str)
return blob;
}
+/**
+ * Create a new data blob from const data
+ */
+
_PUBLIC_ DATA_BLOB data_blob_const(const void *p, size_t length)
{
DATA_BLOB blob;
diff --git a/source4/lib/util/debug.c b/source4/lib/util/debug.c
index 1c5bb25753..e4f13ea28e 100644
--- a/source4/lib/util/debug.c
+++ b/source4/lib/util/debug.c
@@ -29,10 +29,11 @@
* @brief Debug logging
**/
-/* this global variable determines what messages are printed */
+/**
+ * this global variable determines what messages are printed
+ */
_PUBLIC_ int DEBUGLEVEL;
-
/* the registered mutex handlers */
static struct {
const char *name;
@@ -64,7 +65,7 @@ static void log_timestring(int level, const char *location, const char *func)
free(s);
}
-/*
+/**
the backend for debug messages. Note that the DEBUG() macro has already
ensured that the log level has been met before this is called
*/
@@ -74,9 +75,12 @@ _PUBLIC_ void do_debug_header(int level, const char *location, const char *func)
log_task_id();
}
-/*
+/**
the backend for debug messages. Note that the DEBUG() macro has already
ensured that the log level has been met before this is called
+
+ @note You should never have to call this function directly. Call the DEBUG()
+ macro instead.
*/
_PUBLIC_ void do_debug(const char *format, ...) _PRINTF_ATTRIBUTE(1,2)
{
diff --git a/source4/lib/util/debug.h b/source4/lib/util/debug.h
index 4cd5759119..10d7d0697c 100644
--- a/source4/lib/util/debug.h
+++ b/source4/lib/util/debug.h
@@ -18,6 +18,11 @@
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
+/**
+ * @file
+ * @brief Debugging macros
+ */
+
/* If we have these macros, we can add additional info to the header. */
#ifdef HAVE_FUNCTION_MACRO
@@ -54,10 +59,21 @@ extern int DEBUGLEVEL;
do_debug body; \
} \
} while (0)
+/**
+ * Write to the debug log.
+ */
#define DEBUG(level, body) _DEBUG(level, body, True)
+/**
+ * Add data to an existing debug log entry.
+ */
#define DEBUGADD(level, body) _DEBUG(level, body, False)
-#define DEBUGC(class, level, body) DEBUG(level, body)
-#define DEBUGADDC(class, level, body) DEBUGADD(level, body)
+
+/**
+ * Obtain indentation string for the debug log.
+ *
+ * Level specified by n.
+ */
#define DEBUGTAB(n) do_debug_tab(n)
+/** Possible destinations for the debug log */
enum debug_logtype {DEBUG_STDOUT = 0, DEBUG_FILE = 1, DEBUG_STDERR = 2};
diff --git a/source4/lib/util/genrand.c b/source4/lib/util/genrand.c
index f2b038f161..5bdf1f7e08 100644
--- a/source4/lib/util/genrand.c
+++ b/source4/lib/util/genrand.c
@@ -46,6 +46,9 @@ _PUBLIC_ void set_rand_reseed_callback(void (*fn)(int *))
set_need_random_reseed();
}
+/**
+ * Tell the random number generator it needs to reseed.
+ */
_PUBLIC_ void set_need_random_reseed(void)
{
done_reseed = False;
@@ -299,6 +302,13 @@ _PUBLIC_ char *generate_random_str_list(TALLOC_CTX *mem_ctx, size_t len, const c
return retstr;
}
+/**
+ * Generate a random text string consisting of the specified length.
+ * The returned string will be allocated.
+ *
+ * Characters used are: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+_-#.,
+ */
+
_PUBLIC_ char *generate_random_str(TALLOC_CTX *mem_ctx, size_t len)
{
char *retstr;
diff --git a/source4/lib/util/mutex.h b/source4/lib/util/mutex.h
index 018c134bcb..bdc7bc7e7a 100644
--- a/source4/lib/util/mutex.h
+++ b/source4/lib/util/mutex.h
@@ -21,6 +21,11 @@
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
+/**
+ * @file
+ * @brief Mutex operations
+ */
+
struct mutex_ops;
/* To add a new read/write lock, add it to enum rwlock_id
diff --git a/source4/lib/util/unix_privs.c b/source4/lib/util/unix_privs.c
index 13b0aa203c..c94cf619a3 100644
--- a/source4/lib/util/unix_privs.c
+++ b/source4/lib/util/unix_privs.c
@@ -59,6 +59,12 @@ static int privileges_destructor(void *ptr)
return 0;
}
+/**
+ * Obtain root privileges for the current process.
+ *
+ * The privileges can be dropped by talloc_free()-ing the
+ * token returned by this function
+ */
void *root_privileges(void)
{
struct saved_state *s;
diff --git a/source4/lib/util/util.c b/source4/lib/util/util.c
index 81084878b5..ec25a9cbc7 100644
--- a/source4/lib/util/util.c
+++ b/source4/lib/util/util.c
@@ -93,6 +93,12 @@ _PUBLIC_ BOOL directory_exist(const char *dname)
return ret;
}
+/**
+ * Try to create the specified directory if it didn't exist.
+ *
+ * @retval True if the directory already existed and has the right permissions
+ * or was successfully created.
+ */
_PUBLIC_ BOOL directory_create_or_exist(const char *dname, uid_t uid,
mode_t dir_perms)
{
@@ -486,6 +492,11 @@ static void print_asc(int level, const uint8_t *buf,int len)
DEBUGADD(level,("%c", isprint(buf[i])?buf[i]:'.'));
}
+/**
+ * Write dump of binary data to the log file.
+ *
+ * The data is only written if the log level is at least level.
+ */
_PUBLIC_ void dump_data(int level, const uint8_t *buf,int len)
{
int i=0;
@@ -688,6 +699,12 @@ static char *modules_path(TALLOC_CTX* mem_ctx, const char *name)
return talloc_asprintf(mem_ctx, "%s/%s", dyn_MODULESDIR, name);
}
+/**
+ * Load the initialization functions from DSO files for a specific subsystem.
+ *
+ * Will return an array of function pointers to initialization functions
+ */
+
_PUBLIC_ init_module_fn *load_samba_modules(TALLOC_CTX *mem_ctx, const char *subsystem)
{
char *path = modules_path(mem_ctx, subsystem);
@@ -700,6 +717,12 @@ _PUBLIC_ init_module_fn *load_samba_modules(TALLOC_CTX *mem_ctx, const char *sub
return ret;
}
+/**
+ * Write a password to the log file.
+ *
+ * @note Only actually does something if DEBUG_PASSWORD was defined during
+ * compile-time.
+ */
_PUBLIC_ void dump_data_pw(const char *msg, const uint8_t * data, size_t len)
{
#ifdef DEBUG_PASSWORD
diff --git a/source4/lib/util/util.h b/source4/lib/util/util.h
index 272cc13f4e..1dfd942dd3 100644
--- a/source4/lib/util/util.h
+++ b/source4/lib/util/util.h
@@ -100,8 +100,20 @@ struct substitute_context;
#define SAFE_FREE(x) do { if ((x) != NULL) {free(discard_const_p(void *, (x))); (x)=NULL;} } while(0)
#endif
+/**
+ * Type-safe version of malloc. Allocated one copy of the
+ * specified data type.
+ */
#define malloc_p(type) (type *)malloc(sizeof(type))
+
+/**
+ * Allocate an array of elements of one data type. Does type-checking.
+ */
#define malloc_array_p(type, count) (type *)realloc_array(NULL, sizeof(type), count)
+
+/**
+ * Resize an array of elements of one data type. Does type-checking.
+ */
#define realloc_p(p, type, count) (type *)realloc_array(p, sizeof(type), count)
#if defined(VALGRIND)
@@ -127,6 +139,8 @@ struct substitute_context;
makes the return type safe.
*/
#define discard_const(ptr) ((void *)((intptr_t)(ptr)))
+
+/** Type-safe version of discard_const */
#define discard_const_p(type, ptr) ((type *)discard_const(ptr))
#endif /* _SAMBA_UTIL_H_ */
diff --git a/source4/lib/util/util_str.c b/source4/lib/util/util_str.c
index ef6abd6e83..4bb3ea1b54 100644
--- a/source4/lib/util/util_str.c
+++ b/source4/lib/util/util_str.c
@@ -436,6 +436,9 @@ _PUBLIC_ size_t strhex_to_str(char *p, size_t len, const char *strhex)
return num_chars;
}
+/**
+ * Parse a hex string and return a data blob.
+ */
_PUBLIC_ DATA_BLOB strhex_to_data_blob(const char *strhex)
{
DATA_BLOB ret_blob = data_blob(NULL, strlen(strhex)/2+1);
@@ -643,6 +646,9 @@ _PUBLIC_ char *strchr_m(const char *s, char c)
return NULL;
}
+/**
+ * Multibyte-character version of strrchr
+ */
_PUBLIC_ char *strrchr_m(const char *s, char c)
{
char *ret = NULL;
@@ -665,7 +671,7 @@ _PUBLIC_ char *strrchr_m(const char *s, char c)
return ret;
}
-/*
+/**
return True if any (multi-byte) character is lower case
*/
_PUBLIC_ BOOL strhaslower(const char *string)
@@ -688,7 +694,7 @@ _PUBLIC_ BOOL strhaslower(const char *string)
return False;
}
-/*
+/**
return True if any (multi-byte) character is upper case
*/
_PUBLIC_ BOOL strhasupper(const char *string)
@@ -1016,6 +1022,12 @@ _PUBLIC_ const char *str_format_nbt_domain(TALLOC_CTX *mem_ctx, const char *s)
return ret;
}
+/**
+ * Add a string to an array of strings.
+ *
+ * num should be a pointer to an integer that holds the current
+ * number of elements in strings. It will be updated by this function.
+ */
_PUBLIC_ BOOL add_string_to_array(TALLOC_CTX *mem_ctx,
const char *str, const char ***strings, int *num)
{
@@ -1137,6 +1149,13 @@ _PUBLIC_ BOOL set_boolean(const char *boolean_string, BOOL *boolean)
return False;
}
+/**
+ * Parse a string containing a boolean value.
+ *
+ * val will be set to the read value.
+ *
+ * @retval True if a boolean value was parsed, False otherwise.
+ */
_PUBLIC_ BOOL conv_str_bool(const char * str, BOOL * val)
{
char * end = NULL;
@@ -1192,6 +1211,13 @@ _PUBLIC_ BOOL conv_str_size(const char * str, uint64_t * val)
return True;
}
+/**
+ * Parse a uint64_t value from a string
+ *
+ * val will be set to the value read.
+ *
+ * @retval True if parsing was successful, False otherwise
+ */
_PUBLIC_ BOOL conv_str_u64(const char * str, uint64_t * val)
{
char * end = NULL;
diff --git a/source4/lib/util/xfile.c b/source4/lib/util/xfile.c
index 43f0f85f52..97bab2ef9a 100644
--- a/source4/lib/util/xfile.c
+++ b/source4/lib/util/xfile.c
@@ -51,7 +51,7 @@ XFILE *x_stderr = &_x_stderr;
#define X_FLAG_ERROR 2
#define X_FLAG_EINVAL 3
-/* simulate setvbuf() */
+/** simulate setvbuf() */
int x_setvbuf(XFILE *f, char *buf, int mode, size_t size)
{
x_fflush(f);
@@ -93,7 +93,7 @@ static int x_allocate_buffer(XFILE *f)
}
-/* this looks more like open() than fopen(), but that is quite deliberate.
+/** this looks more like open() than fopen(), but that is quite deliberate.
I want programmers to *think* about O_EXCL, O_CREAT etc not just
get them magically added
*/
@@ -126,7 +126,7 @@ XFILE *x_fopen(const char *fname, int flags, mode_t mode)
return ret;
}
-/* simulate fclose() */
+/** simulate fclose() */
int x_fclose(XFILE *f)
{
int ret;
@@ -150,7 +150,7 @@ int x_fclose(XFILE *f)
return ret;
}
-/* simulate fwrite() */
+/** simulate fwrite() */
size_t x_fwrite(const void *p, size_t size, size_t nmemb, XFILE *f)
{
ssize_t ret;
@@ -195,7 +195,7 @@ size_t x_fwrite(const void *p, size_t size, size_t nmemb, XFILE *f)
return total/size;
}
-/* thank goodness for asprintf() */
+/** thank goodness for asprintf() */
int x_vfprintf(XFILE *f, const char *format, va_list ap)
{
char *p;
@@ -228,7 +228,7 @@ int x_fileno(XFILE *f)
return f->fd;
}
-/* simulate fflush() */
+/** simulate fflush() */
int x_fflush(XFILE *f)
{
int ret;
@@ -255,33 +255,33 @@ int x_fflush(XFILE *f)
return 0;
}
-/* simulate setbuffer() */
+/** simulate setbuffer() */
void x_setbuffer(XFILE *f, char *buf, size_t size)
{
x_setvbuf(f, buf, buf?X_IOFBF:X_IONBF, size);
}
-/* simulate setbuf() */
+/** simulate setbuf() */
void x_setbuf(XFILE *f, char *buf)
{
x_setvbuf(f, buf, buf?X_IOFBF:X_IONBF, XBUFSIZE);
}
-/* simulate setlinebuf() */
+/** simulate setlinebuf() */
void x_setlinebuf(XFILE *f)
{
x_setvbuf(f, NULL, X_IOLBF, 0);
}
-/* simulate feof() */
+/** simulate feof() */
int x_feof(XFILE *f)
{
if (f->flags & X_FLAG_EOF) return 1;
return 0;
}
-/* simulate ferror() */
+/** simulate ferror() */
int x_ferror(XFILE *f)
{
if (f->flags & X_FLAG_ERROR) return 1;
@@ -303,7 +303,7 @@ static void x_fillbuf(XFILE *f)
f->next = f->buf;
}
-/* simulate fgetc() */
+/** simulate fgetc() */
int x_fgetc(XFILE *f)
{
int ret;
@@ -323,7 +323,7 @@ int x_fgetc(XFILE *f)
return ret;
}
-/* simulate fread */
+/** simulate fread */
size_t x_fread(void *p, size_t size, size_t nmemb, XFILE *f)
{
size_t total = 0;
@@ -336,7 +336,7 @@ size_t x_fread(void *p, size_t size, size_t nmemb, XFILE *f)
return total/size;
}
-/* simulate fgets() */
+/** simulate fgets() */
char *x_fgets(char *s, int size, XFILE *stream)
{
char *s0 = s;
@@ -355,7 +355,8 @@ char *x_fgets(char *s, int size, XFILE *stream)
return s0;
}
-/* trivial seek, works only for SEEK_SET and SEEK_END if SEEK_CUR is
+/**
+ * trivial seek, works only for SEEK_SET and SEEK_END if SEEK_CUR is
* set then an error is returned */
off_t x_tseek(XFILE *f, off_t offset, int whence)
{
generated by cgit (git 2.34.1) at 2024-12-03 20:38:33 +0000