Miscellaneous

Defines
#define	U_PATH_MAX   4096
	Maximum path length.
#define	U_NAME_MAX   512
	Maximum file name length.
#define	U_FILENAME_MAX   (U_PATH_MAX + U_NAME_MAX)
	Maximum length for a fully qualified file name.
Typedefs
typedef ssize_t(*	iof_t )(int, void *, size_t)
	Prototype for an I/O driver function used by u_io, e.g. read(2) or write(2).
Functions
char *	u_strdup (const char *s)
	Allocate sufficient memory for a copy of the supplied string, copy it, and return a reference to the copy.
char *	u_strndup (const char *s, size_t len)
	Make a copy of a portion of a string.
int	u_atol (const char *nptr, long *pl)
	Convert string to long int representation.
int	u_atoi (const char *nptr, int *pi)
	Convert string to int representation.
int	u_atof (const char *nptr, double *pd)
	Convert string to double representation.
int	u_data_dump (char *data, size_t sz, const char *file)
	Save some data in memory to file.
int	u_data_is_bin (char *data, size_t sz)
	Tell if the supplied buffer contains non-ASCII bytes.
int	u_io (iof_t f, int sd, void *buf, size_t l, ssize_t *n, int *eof)
	Top level I/O routine.
int	u_isblank (int c)
	Tell if the supplied char is a space or tab.
int	u_isblank_str (const char *s)
	Tell if the supplied string is blank.
int	u_isnl (int c)
	Tell if the supplied char is a new-line character.
int	u_load_file (const char *path, size_t sz_max, char **pbuf, size_t *psz)
	Load file into memory from the supplied FS entry.
int	u_path_snprintf (char *buf, size_t sz, char sep, const char *fmt,...)
	snprintf(3)-like function that handles path name building
int	u_savepid (const char *pf)
	Save the process id of the calling process to file.
int	u_sleep (unsigned int secs)
	sleep(3) wrapper that handles EINTR
int	u_snprintf (char *str, size_t size, const char *fmt,...)
	snprintf(3) wrapper
int	u_strlcat (char *dst, const char *src, size_t size)
	Wrapper to strlcat(3).
int	u_strlcpy (char *dst, const char *src, size_t size)
	Wrapper to strlcpy(3).
int	u_strtok (const char *s, const char *delim, char ***ptv, size_t *pnelems)
	Break a string into pieces separated by a given set of characters.
ssize_t	u_read (int fd, void *buf, size_t size)
	An u_io wrapper that uses read(2) as I/O driver.
ssize_t	u_write (int fd, void *buf, size_t size)
	An u_io wrapper that uses write(2) as I/O driver.
void	u_strtok_cleanup (char **tv, size_t nelems)
	Cleanup the strings vector created by u_strtok.
void	u_trim (char *s)
	Removes leading and trailing blanks (spaces and tabs) from a string.
void	u_use_unused_args (char *dummy,...)
	Consume an arbitrary number of variable names.
void *	u_memdup (const void *src, size_t size)
	Make a duplicate of a memory block.
int	u_tokenize (char *wlist, const char *delim, char **tokv, size_t tokv_sz)
	tokenize the supplied wlist string (DEPRECATED, use u_strtok instead)
char *	u_sstrncpy (char *dst, const char *src, size_t size)
	Safe string copy (DEPRECATED, use u_strlcpy instead).
int	u_atoumax (const char *nptr, uintmax_t *pumax)
	Convert string to u_intmax_t representation.

---

Function Documentation

int u_atof	(	const char *	nptr,
		double *	pd
	)

Try to convert the string nptr into a double precision FP number at pl, handling all strtod(3) exceptions (overflow or underflow, invalid representation) in a simple go/no-go way. Beware that if your platform does not implements the strtod(3) interface, this function falls back using plain old atof(3) which does have severe limitations as of error handling and thread safety.

Parameters:

	nptr	NUL-terminated string (possibly) representing an floating point number (see strtod(3) for formatting details)
	pd	pointer to a double variable that contains the result of a successful conversion

Return values:

	0	on success (always if HAVE_STRTOD is not defined)
	~0	on error

Definition at line 836 of file srcs/toolbox/misc.c.

Referenced by u_json_get_real().

int u_atoi	(	const char *	nptr,
		int *	pi
	)

Try to convert the string nptr into an integer at pi, handling all strtol(3) exceptions (overflow or underflow, invalid representation) in a simple go/no-go way.

Parameters:

	nptr	NUL-terminated string (possibly) representing an integer value (base 10)
	pi	pointer to an integer variable that contains the result of a successful conversion

Return values:

	0	on success
	~0	on error

Definition at line 758 of file srcs/toolbox/misc.c.

References u_atol().

Referenced by u_config_get_subkey_value_i().

int u_atol	(	const char *	nptr,
		long *	pl
	)

Try to convert the string nptr into a long integer at pl, handling all strtol(3) exceptions (overflow or underflow, invalid representation) in a simple go/no-go way.

Parameters:

	nptr	NUL-terminated string (possibly) representing an integer value (base 10)
	pl	pointer to a long int variable that contains the result of a successful conversion

Return values:

	0	on success
	~0	on error

Definition at line 716 of file srcs/toolbox/misc.c.

Referenced by u_atoi(), and u_json_get_int().

int u_atoumax	(	const char *	nptr,
		uintmax_t *	pumax
	)

Try to convert the string nptr into a maximum unsigned integer at pumax, handling all strtoumax(3) exceptions (overflow or underflow, invalid representation) in a simple go/no-go way.

Parameters:

	nptr	NUL-terminated string (possibly) representing an unsigned integer value (base 10)
	pumax	pointer to an u_intmax_t variable that contains the result of a successful conversion

Return values:

	0	on success
	~0	on error

Definition at line 795 of file srcs/toolbox/misc.c.

int u_data_dump	(	char *	data,
		size_t	sz,
		const char *	file
	)

Save some memory starting from data for sz bytes to the supplied file

Parameters:

	data	pointer to the data to be saved
	sz	size in bytes of data
	file	the path of the file where data will be saved

Return values:

	0	on success
	~0	on error

Definition at line 500 of file srcs/toolbox/misc.c.

Referenced by u_buf_save().

int u_data_is_bin	(	char *	data,
		size_t	sz
	)

Tell if the supplied buffer data contains non-ASCII bytes in the first sz bytes

Parameters:

	data	the data buffer that shall be examined
	sz	the number of bytes that will be taken into account

Return values:

	1	if there is at least one non-ASCII character
	0	if it data contains only ASCII characters

Definition at line 95 of file srcs/toolbox/misc.c.

int u_io	(	iof_t	f,
		int	sd,
		void *	buf,
		size_t	l,
		ssize_t *	n,
		int *	eof
	)

Try to read/write - atomically - a chunk of l bytes from/to the object referenced by the descriptor sd. The data chunk is written to/read from the buffer starting at buf. An I/O driver function f is used to carry out the job whose interface and behaviour must conform to those of POSIX.1 read(2) or write(2). If n is not NULL, it will store the number of bytes actually read/written: this information is significant only when u_io fails. If eof is not NULL, it will be set to 1 on an EOF condition.

Parameters:

	f	the I/O function, i.e. read(2) or write(2)
	sd	the file descriptor on which the I/O operation is performed
	buf	the data chunk to be read or written
	l	the length in bytes of buf
	n	the number of bytes read/written as a value-result arg
	eof	true if end-of-file condition

Return values:

	0	is returned on success
	~0	is returned if an error other than EINTR has occurred, or if the requested amount of data could not be entirely read/written.

Definition at line 581 of file srcs/toolbox/misc.c.

Referenced by u_read(), and u_write().

int u_isblank

(

int

c

)

[inline]

Tell if the supplied char is a space or tab

Parameters:

c

the character to be tested

Return values:

	1	if c is whitespace or tab character
	0	if c is neither a whitespace nor tab character

Definition at line 41 of file srcs/toolbox/misc.c.

Referenced by u_isblank_str(), and u_trim().

int u_isblank_str

(

const char *

s

)

[inline]

Tell if the supplied string is composed of tabs and/or spaces only

Parameters:

s

a NUL-terminated string that is is being queried

Return values:

	1	if s is blank
	0	if s contains non-blank characters

Definition at line 56 of file srcs/toolbox/misc.c.

References u_isblank().

int u_isnl

(

int

c

)

[inline]

Tell if the supplied char is a new-line character, i.e. CR (\r) or LF (\n)

Parameters:

c

the character to be tested

Return values:

	1	if c is CR or LF
	0	if c is neither CR nor LF

Definition at line 78 of file srcs/toolbox/misc.c.

int u_load_file	(	const char *	path,
		size_t	sz_max,
		char **	pbuf,
		size_t *	psz
	)

Parameters:

	path	the path name of the file
	sz_max	if >0 impose this size limit (otherwise unlimited)
	pbuf	the pointer to the memory location holding the file's contents as a value-result argument
	psz	size of the loaded file as a v-r argument

Return values:

	0	on success
	~0	on error

Definition at line 526 of file srcs/toolbox/misc.c.

References u_zalloc().

void * u_memdup	(	const void *	src,
		size_t	size
	)

Duplicate the memory block starting at src of size size

Parameters:

	src	reference to the block that must be copied
	size	number of bytes that must be copied

Returns:

the reference to the duplicated block of memory on success, NULL on error.

Definition at line 457 of file srcs/toolbox/misc.c.

References u_malloc().

int u_path_snprintf	(	char *	buf,
		size_t	sz,
		char	sep,
		const char *	fmt,
			...
	)

Call snprintf(3) with the provided arguments and remove consecutive path separators from the resulting string

Parameters:

	buf	destination buffer
	sz	size of str
	sep	path separator to use (/ or \)
	fmt	printf(3) format string

Return values:

	0	on success
	~0	on failure

Definition at line 392 of file srcs/toolbox/misc.c.

ssize_t u_read	(	int	fd,
		void *	buf,
		size_t	size
	)

An u_io wrapper that uses read(2) as I/O driver: its behaviour is identical to read(2) except it automatically restarts when interrupted

Parameters:

	fd	an open file descriptor
	buf	buffer to read into
	size	size of buf in bytes

Returns:

on success the number of read bytes (that will always be size except that on EOF) is returned; on failure return -1

Definition at line 635 of file srcs/toolbox/misc.c.

References u_io().

int u_savepid

(

const char *

pf

)

Save the process id of the calling process to the supplied file pf

Parameters:

pf

path of the file (be it fully qualified or relative to the current working directory) where the pid will be saved

Return values:

	0	on success
	~0	on error

Definition at line 430 of file srcs/toolbox/misc.c.

int u_sleep

(

unsigned int

secs

)

sleep(3) wrapper that automatically restarts when interrupted by a signal

Parameters:

secs

number of seconds to sleep

Return values:

	0	on success
	-1	on failure

Definition at line 683 of file srcs/toolbox/misc.c.

int u_snprintf	(	char *	str,
		size_t	size,
		const char *	fmt,
			...
	)

snprintf(3) wrapper

Parameters:

	str	destination buffer
	size	size of str
	fmt	printf(3) format string

Return values:

	0	on success
	~0	on failure, i.e. if an output error has occurred, or the destination buffer would have been overflowed

Definition at line 359 of file srcs/toolbox/misc.c.

Referenced by u_env_init(), u_hmap_put(), u_inet_ntop(), u_json_array_get_nth(), u_json_cache_get(), u_json_new_int(), u_json_new_real(), and u_sa_ntop().

char * u_sstrncpy	(	char *	dst,
		const char *	src,
		size_t	size
	)

Safe string copy which NUL-terminates the destination string dst before copying the source string src for no more than size bytes

Note:

DEPRECATED, use u_strlcpy instead

Parameters:

	dst	buffer of at least size bytes where src will be copied
	src	NUL-terminated string that is (possibly) copied to dst
	size	full size of the destination buffer dst

Returns:

a pointer to the destination string dst

Definition at line 937 of file srcs/toolbox/misc.c.

char * u_strdup

(

const char *

s

)

Allocate sufficient memory for a copy of the supplied string s, copy it, and return its reference. The returned pointer may subsequently be used as an argument to u_free.

Parameters:

s

a NUL-terminated string

Returns:

the duplicated string or NULL in case no sufficient memory is available

Definition at line 183 of file srcs/toolbox/misc.c.

References u_strndup().

Referenced by u_config_add_child(), u_config_set_value(), u_hmap_o_new(), u_lexer_new(), and u_strtok().

int u_strlcat	(	char *	dst,
		const char *	src,
		size_t	size
	)			[inline]

Wrapper to strlcat(3) that will check whether src is too big to fit dst. In any case at least size bytes of src will be concatenated to dst.

Parameters:

	dst	NUL-terminated string to which src will be concatenated
	src	NUL-terminated string that is (possibly) contatenated to dst
	size	full size of the destination buffer dst

Return values:

	0	string concatenation is ok
	~0	string concatenation would overflow the destination buffer

Definition at line 223 of file srcs/toolbox/misc.c.

Referenced by u_uri_knead().

int u_strlcpy	(	char *	dst,
		const char *	src,
		size_t	size
	)			[inline]

Wrapper to strlcpy(3) that will check whether src is too big to fit dst. In case of overflow, at least size bytes will be copied anyway from src to dst.

Parameters:

	dst	buffer of at least size bytes where bytes from src will be copied
	src	NUL-terminated string that is (possibly) copied to dst
	size	full size of the destination buffer dst

Return values:

	0	copy is ok
	~0	copy would overflow the destination buffer

Definition at line 203 of file srcs/toolbox/misc.c.

Referenced by u_config_save_to_buf(), u_inet_ntop(), u_json_cache_set_tv(), u_json_set_key(), u_pwd_auth_user(), u_pwd_init(), u_sa_ntop(), u_test_new(), and u_test_set_outfn().

char * u_strndup	(	const char *	s,
		size_t	len
	)

Return a NUL-terminated string which duplicates the first len characters of the supplied string s. The returned pointer may subsequently be used as an argument to u_free.

Parameters:

	s	a NUL-terminated string
	len	the length of the substring which has to be copied

Returns:

the duplicated substring, or NULL on error (i.e. insufficient memory or invalid len)

Definition at line 154 of file srcs/toolbox/misc.c.

References u_malloc().

Referenced by u_config_get_subkey_nth(), and u_strdup().

int u_strtok	(	const char *	s,
		const char *	delim,
		char ***	ptv,
		size_t *	pnelems
	)

Tokenize the delim separated string s and place its *pnelems pieces into the string array *ptv. The *ptv result argument contains all the pieces at increasing indices [0..*pnelems-1] in the order they've been found in string s. At index *pnelems - i.e. *ptv[*pnelems] - the pointer to a (clobbered) duplicate of s is stored, which must be free'd along with the string array result *ptv once the caller is done with it:

      size_t nelems, i;
      char **tv = NULL;
          
      // break string into pieces
      dbg_err_if (u_strtok("white spaces separated s", " ", &tv, &nelems));

      // use found tokens
      for (i = 0; i < nelems; i++)
          con("%s", tv[i]);

      // free memory
      u_strtok_cleanup(tv, nelems);

The aforementioned disposal must be carried out every time the function returns successfully, even if the number of found tokens is zero (i.e. s contains separator chars only, or is an empty string).

Parameters:

	s	the string that shall be broken up
	delim	the set of allowed delimiters as a string
	ptv	the pieces as a result string array
	pnelems	the number of tokens actually separated

Return values:

	0	on success
	~0	on error

Definition at line 266 of file srcs/toolbox/misc.c.

References u_realloc(), and u_strdup().

void u_strtok_cleanup	(	char **	tv,
		size_t	nelems
	)

Cleanup the strings vector created by u_strtok

Parameters:

	tv	the strings vector created by a previous call to u_strtok
	nelems	number of elements in tv (as returned by u_strtok)

Returns:

nothing

Definition at line 335 of file srcs/toolbox/misc.c.

References u_free().

int u_tokenize	(	char *	wlist,
		const char *	delim,
		char **	tokv,
		size_t	tokv_sz
	)

Tokenize the delim separated string wlist and place its pieces (at most tokv_sz - 1) into tokv.

Note:

DEPRECATED, use u_strtok instead

Parameters:

	wlist	list of strings possibily separated by chars in delim
	delim	set of token separators
	tokv	pre-allocated string array
	tokv_sz	number of cells in tokv array

Return values:

	0	on success
	~0	on error

Definition at line 895 of file srcs/toolbox/misc.c.

void u_trim

(

char *

s

)

Remove leading and trailing blanks (spaces and tabs) from the supplied string s

Parameters:

s

a NUL-terminated string

return nothing

Definition at line 118 of file srcs/toolbox/misc.c.

References u_isblank().

Referenced by u_string_trim().

void u_use_unused_args	(	char *	dummy,
			...
	)			[inline]

Consume an arbitrary number of variable names: it is used to silent the GNU C compiler when invoked with -Wunused, and you know that a given variable won't be never used.

Parameters:

dummy

the first of a possibly long list of meaningless parameters

Returns:

nothing

Definition at line 480 of file srcs/toolbox/misc.c.

ssize_t u_write	(	int	fd,
		void *	buf,
		size_t	size
	)

An u_io wrapper that uses write(2) as I/O driver: its behaviour is identical to write(2) except it automatically restarts when interrupted

Parameters:

	fd	an open file descriptor
	buf	buffer to write
	size	size of buf in bytes

Return values:

	size	on success
	-1	on error

Definition at line 665 of file srcs/toolbox/misc.c.

References u_io().