mirror of
https://github.com/samba-team/samba.git
synced 2025-03-27 22:50:26 +03:00
r13849: More improvements to the libutil docs.
(This used to be commit eed16ac3b7f7062a34f09f602db0f828cac7f246)
This commit is contained in:
Jelmer Vernooij
Gerald (Jerry) Carter
parent
8ef42b1fab
commit
4d8fe47f7f
@ -132,36 +132,9 @@ enum brl_type {
|
||||
|
||||
#include "util/safe_string.h"
|
||||
|
||||
extern int DEBUGLEVEL;
|
||||
|
||||
#if defined(VALGRIND)
|
||||
#define strlen(x) valgrind_strlen(x)
|
||||
#endif
|
||||
|
||||
#if 0
|
||||
/* darn, we can't do this now that we don't link the ldb tools to all the smb libs */
|
||||
#define TALLOC_ABORT(reason) smb_panic(reason)
|
||||
#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 /* _INCLUDES_H */
|
||||
|
||||
@ -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));
|
||||
11
source4/lib/util/mainpage.dox
Normal file
11
source4/lib/util/mainpage.dox
Normal file
@ -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.
|
||||
|
||||
*/
|
||||
@ -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_ */
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user