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().


←Products
© 2005-2012 - KoanLogic S.r.l. - All rights reserved