Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages

misc.h File Reference

Detailed Description

Misc functions.

This misc.[ch] provides several miscellaneous small routines & macros for:

Author:
Raphael Manfredi
Date:
2001-2003

#include "config.h"
#include <time.h>
#include <stdio.h>
#include <ctype.h>
#include <glib.h>

Go to the source code of this file.

Defines

#define SIZE_FIELD_MAX   64 /**< Max size of sprintf-ed size quantity */
 Max size of sprintf-ed size quantity.

#define GUID_RAW_SIZE   16 /**< Binary representation of 128 bits */
 Binary representation of 128 bits.

#define GUID_HEX_SIZE   32 /**< Hexadecimal GUID representation */
 Hexadecimal GUID representation.

#define g_string_printf   g_string_sprintf
#define g_strlcpy   strlcpy
#define g_strlcat   strlcat
#define CONST_STRLEN(x)   (sizeof(x) - 1)
#define G_N_ELEMENTS(arr)   (sizeof (arr) / sizeof ((arr)[0]))
#define set_flags(r, f)   (r |= (f))
#define clear_flags(r, f)   (r &= ~(f))
#define UINT8_HEX_BUFLEN   (sizeof "FF")
#define UINT8_DEC_BUFLEN   (sizeof "255")
#define UINT16_HEX_BUFLEN   (sizeof "01234")
#define UINT16_DEC_BUFLEN   (sizeof "65535")
#define UINT32_HEX_BUFLEN   (sizeof "012345678")
#define UINT32_DEC_BUFLEN   (sizeof "4294967295")
#define UINT64_HEX_BUFLEN   (sizeof "0123456789ABCDEF")
#define UINT64_DEC_BUFLEN   (sizeof "18446744073709551615")
#define IPV4_ADDR_BUFLEN   (sizeof "255.255.255.255")
#define IPV6_ADDR_BUFLEN   (sizeof "0001:0203:0405:0607:0809:1011:255.255.255.255")
#define TIMESTAMP_BUF_LEN   (sizeof "9999-12-31 23:59:61")
#define port_is_valid(port)   (port != 0)
#define USE_DIFFTIME
#define delta_time(a, b)   ((gint64) difftime((a), (b)))
#define NULL_STRING(s)   (NULL != (s) ? (s) : "(null)")
#define EMPTY_STRING(s)   (NULL != (s) ? (s) : "")
#define BINARY_SEARCH(bs_type, bs_key, bs_size, bs_cmp, bs_get_key, bs_found)
 Perform a binary search over an array.

#define BINARY_ARRAY_SORTED(bs_array, bs_type, bs_field, bs_cmp, bs_field2str)
 Ensure a table used for binary search is sorted.


Typedefs

typedef void(* func_ptr_t )(void)
typedef guint16 flag_t
typedef void(* signal_handler_t )(gint signo)
typedef void(* cidr_split_t )(guint32 ip, guint bits, gpointer udata)

Functions

size_t strlcpy (gchar *dst, const gchar *src, size_t dst_size)
 Needs to be defined if we are not using Glib 2.

size_t strlcat (gchar *dst, const gchar *src, size_t dst_size)
size_t concat_strings (gchar *dst, size_t size, const gchar *s,...) WARN_NEED_SENTINEL
 Concatenates a variable number of NUL-terminated strings into ``dst''.

size_t w_concat_strings (gchar **dst, const gchar *first,...) WARN_NEED_SENTINEL
 Concatenates a variable number of NUL-terminated strings into buffer which will be allocated using walloc().

G_GNUC_CONST WARN_UNUSED_RESULT
gchar * 		deconstify_gchar (const gchar *p)
 Cast a ``const gchar *'' to ``gchar *''.

G_GNUC_CONST WARN_UNUSED_RESULT
guint32 * 		deconstify_guint32 (const guint32 *p)
G_GNUC_CONST WARN_UNUSED_RESULT
gpointer 		deconstify_gpointer (gconstpointer p)
G_GNUC_CONST WARN_UNUSED_RESULT
gconstpointer 		cast_to_gconstpointer (gconstpointer p)
G_GNUC_CONST WARN_UNUSED_RESULT
gpointer 		cast_to_gpointer (gpointer p)
G_GNUC_CONST WARN_UNUSED_RESULT
gchar * 		cast_to_gchar_ptr (gpointer p)
G_GNUC_CONST WARN_UNUSED_RESULT
guchar * 		cast_to_guchar_ptr (gpointer p)
G_GNUC_CONST WARN_UNUSED_RESULT
gpointer 		cast_func_to_gpointer (func_ptr_t f)
G_GNUC_CONST WARN_UNUSED_RESULT
func_ptr_t 		cast_gpointer_to_func (gconstpointer p)
gint ascii_strcasecmp (const gchar *s1, const gchar *s2)
 Same as strcasecmp() but only case-insensitive for ASCII characters.

gint ascii_strncasecmp (const gchar *s1, const gchar *s2, size_t len)
 Same as strncasecmp() but only case-insensitive for ASCII characters.

gint hex2int_inline (guchar c)
 Converts a hexadecimal char (0-9, A-F, a-f) to an integer.

gint dec2int_inline (guchar c)
 Converts a decimal char (0-9) to an integer.

gint alnum2int_inline (guchar c)
 Converts an alphanumeric char (0-9, A-Z, a-z) to an integer.

G_GNUC_CONST WARN_UNUSED_RESULT
gboolean 		is_ascii_blank (gint c)
 ctype-like functions that allow only ASCII characters whereas the locale would allow others.

G_GNUC_CONST WARN_UNUSED_RESULT
gboolean 		is_ascii_cntrl (gint c)
G_GNUC_CONST WARN_UNUSED_RESULT
gboolean 		is_ascii_digit (gint c)
G_GNUC_CONST WARN_UNUSED_RESULT
gboolean 		is_ascii_xdigit (gint c)
G_GNUC_CONST WARN_UNUSED_RESULT
gboolean 		is_ascii_upper (gint c)
G_GNUC_CONST WARN_UNUSED_RESULT
gboolean 		is_ascii_lower (gint c)
G_GNUC_CONST WARN_UNUSED_RESULT
gboolean 		is_ascii_alpha (gint c)
G_GNUC_CONST WARN_UNUSED_RESULT
gboolean 		is_ascii_alnum (gint c)
G_GNUC_CONST WARN_UNUSED_RESULT
gboolean 		is_ascii_space (gint c)
G_GNUC_CONST WARN_UNUSED_RESULT
gboolean 		is_ascii_graph (gint c)
G_GNUC_CONST WARN_UNUSED_RESULT
gboolean 		is_ascii_print (gint c)
G_GNUC_CONST WARN_UNUSED_RESULT
gboolean 		is_ascii_punct (gint c)
G_GNUC_CONST WARN_UNUSED_RESULT
gint 		ascii_toupper (gint c)
G_GNUC_CONST WARN_UNUSED_RESULT
gint 		ascii_tolower (gint c)
WARN_UNUSED_RESULT const gchar * g_strip_context (const gchar *id, const gchar *val)
WARN_UNUSED_RESULT gchar * skip_ascii_spaces (const gchar *s)
 Skips over all ASCII space characters starting at ``s''.

WARN_UNUSED_RESULT gchar * skip_ascii_blanks (const gchar *s)
 Skips over all ASCII blank characters starting at ``s''.

gboolean parse_ipv6_addr (const gchar *s, uint8_t *dst, const gchar **endptr)
const gchar * ipv6_to_string (const guint8 *ipv6)
 Prints the IPv6 address ``ipv6'' to a static buffer.

size_t ipv6_to_string_buf (const guint8 *ipv6, gchar *dst, size_t size)
guint32 string_to_ip (const gchar *)
gboolean string_to_ip_strict (const gchar *s, guint32 *addr, const gchar **ep)
 A strict string to IP address conversion; when other stuff from misc.[ch] is not sufficient.

gboolean string_to_ip_and_mask (const gchar *str, guint32 *ip, guint32 *netmask)
 Extracts the IP address into `ip' and the netmask into `netmask'.

gboolean string_to_ip_port (const gchar *str, guint32 *ip, guint16 *port)
 Decompiles ip:port into ip and port.

const gchar * ip_to_string (guint32)
const gchar * ip_to_string2 (guint32)
size_t ip_to_string_buf (guint32 ip, gchar *buf, size_t size)
const gchar * ip_port_to_string (guint32, guint16)
const gchar * hostname_port_to_string (const gchar *hostname, guint16 port)
const gchar * local_hostname (void)
const gchar * timestamp_to_string (time_t date)
 Convert time to ISO 8601 date plus time, e.g.

const gchar * timestamp_utc_to_string (time_t date)
 Convert time to an ISO 8601 timestamp, e.g.

const gchar * timestamp_rfc822_to_string (time_t date)
 Convert time to RFC-822 style date.

const gchar * timestamp_rfc822_to_string2 (time_t date)
 Same as date_to_rfc822_gchar(), to be able to use the two in the same printf() line.

const gchar * timestamp_rfc1123_to_string (time_t date)
 Convert time to RFC-1123 style date.

size_t timestamp_to_string_buf (time_t date, gchar *dst, size_t size)
 Convert time to ISO 8601 date plus time, e.g.

size_t time_locale_to_string_buf (time_t date, gchar *dst, size_t size)
 Convert time (without the date) to a human-readable string using the time representation of the current locale.

gchar * short_time (gint s)
gchar * short_uptime (gint s)
 Alternate time formatter for uptime.

const gchar * short_size (guint64 size)
const gchar * short_html_size (guint64 size)
 Like short_size() but with unbreakable space between the digits and unit.

const gchar * short_kb_size (guint64 size)
const gchar * short_rate (guint64 rate)
const gchar * compact_size (guint64 size)
const gchar * compact_rate (guint64 rate)
const gchar * compact_kb_size (guint32 size)
gchar * short_value (gchar *buf, size_t size, guint64 v)
gchar * compact_value (gchar *buf, size_t size, guint64 v)
gchar * sha1_base32 (const gchar *sha1)
 Convert binary SHA1 into a base32 string.

gchar * base32_sha1 (const gchar *base32)
 Convert base32 string into binary SHA1.

gchar * guid_hex_str (const gchar *guid)
gboolean hex_to_guid (const gchar *hexguid, gchar *guid)
 Converts hexadecimal string into a GUID.

gchar * guid_base32_str (const gchar *guid)
 Converts GUID into its base32 representation, without the trailing padding.

gchar * base32_to_guid (const gchar *base32)
 Decode the base32 representation of a GUID.

gboolean is_absolute_path (const char *)
 Check whether path is an absolute path.

gboolean is_directory (const gchar *)
 Check whether path is a directory.

gboolean is_regular (const gchar *)
 Check whether path points to a regular file.

gboolean is_symlink (const gchar *)
 Check whether path is a symbolic link.

gboolean file_exists (const gchar *)
 Check for file existence.

guint32 next_pow2 (guint32 n)
G_GNUC_CONST gboolean is_pow2 (guint32 value)
 Checks whether the given value is a power of 2.

void random_init (void)
 Initialize random number generator.

guint32 random_value (guint32 max) WARN_UNUSED_RESULT
void guid_random_fill (gchar *xuid)
 Generate a new random GUID within given `xuid'.

void misc_init (void)
gint str_chomp (gchar *str, gint len)
 Remove antepenultimate char of string if it is a "\r" followed by "\n".

gint hex2int (guchar c)
 Converts a hexadecimal char (0-9, A-F, a-f) to an integer.

gboolean is_printable (const gchar *buf, gint len)
 Check whether buffer contains printable data, suitable for "%s" printing.

void dump_hex (FILE *, const gchar *, gconstpointer, gint)
 Displays hex & ascii lines to the terminal (for debug) Displays the "title" then the characters in "s", # of bytes to print in "b".

void locale_strlower (gchar *, const gchar *)
 Copies ``src'' to ``dst'', converting all upper-case characters to lower-case.

void ascii_strlower (gchar *dst, const gchar *src)
 Copies ``src'' to ``dst'', converting all ASCII upper-case characters to ASCII lower-case.

gint strcmp_delimit (const gchar *a, const gchar *b, const gchar *delimit)
 Compare two strings case-senstive up to the specified delimiters.

gint strcasecmp_delimit (const gchar *a, const gchar *b, const gchar *delimit)
 Compare two strings case-insensitive up to the specified delimiters.

char * unique_filename (const gchar *path, const gchar *file, const gchar *ext)
 Determine unique filename for `file' in `path', with optional trailing extension `ext'.

gchar * hex_escape (const gchar *name, gboolean strict)
 Escape all non-printable chars into the hexadecimal "\xhh" form.

gchar * control_escape (const gchar *s)
 Escape all ASCII control chars (except into the hexadecimal "\xhh" form.

const gchar * lazy_string_to_printf_escape (const gchar *src)
 Escapes a string so that it can be used careless with the POSIX printf tool.

gint highest_bit_set (guint32 n) G_GNUC_CONST
 Determine the highest bit set in `n', -1 if value was 0.

gfloat force_range (gfloat value, gfloat min, gfloat max)
 Enforce range boundaries on a given floating point number.

gchar * make_pathname (const gchar *dir, const gchar *file)
 Create new pathname from the concatenation of the dirname and the basename of the file.

gchar * short_filename (gchar *fullname)
 Determine stripped down path, removing SRC_PREFIX if present.

gchar * data_hex_str (const gchar *data, size_t len)
gint create_directory (const gchar *dir)
 Creates the given directory including sub-directories if necessary.

gboolean filepath_exists (const gchar *dir, const gchar *file)
 Check whether file given by its dirname and its basename exists.

guint16 parse_uint16 (const gchar *, gchar const **, guint, gint *)
guint32 parse_uint32 (const gchar *, gchar const **, guint, gint *)
guint64 parse_uint64 (const gchar *, gchar const **, guint, gint *)
size_t uint32_to_string_buf (guint64 v, gchar *dst, size_t size)
size_t uint64_to_string_buf (guint64 v, gchar *dst, size_t size)
const gchar * uint32_to_string (guint32 v)
const gchar * uint64_to_string (guint64 v)
const gchar * uint64_to_string2 (guint64 v)
gint parse_major_minor (const gchar *src, gchar const **endptr, guint *major, guint *minor)
gchar * is_strprefix (const gchar *s, const gchar *prefix) WARN_UNUSED_RESULT
 Checks whether ``prefix'' is a prefix of ``str''.

gchar * is_strcaseprefix (const gchar *s, const gchar *prefix) WARN_UNUSED_RESULT
 Checks whether ``prefix'' is a prefix of ``str'' performing an case-insensitive (ASCII only) check.

size_t html_escape (const gchar *src, gchar *dst, size_t dst_size)
 Copies the NUL-terminated string ``src'' to ``dst'' replacing all characters which are reserved in HTML with a replacement string.

gint canonize_path (gchar *dst, const gchar *path)
 Creates the canonical representation of a path.

guint compat_max_fd (void)
gint compat_mkdir (const gchar *path, mode_t mode)
size_t compat_pagesize (void)
gpointer compat_page_align (size_t size)
 Allocates a page-aligned memory chunk.

void compat_page_free (gpointer p, size_t size)
gboolean compat_is_superuser (void)
signal_handler_t set_signal (gint signo, signal_handler_t handler)
 Installs a signal handler.

gchar * ascii_strcasestr (const gchar *haystack, const gchar *needle)
 Same as strstr() but case-insensitive with respect to ASCII characters.

G_GNUC_CONST guint32 swap_guint32 (guint32 i)
 Swap endianness of a guint32.

G_GNUC_CONST WARN_UNUSED_RESULT
guint8 		netmask_to_cidr (guint32 netmask)
 Converts the given IPv4 netmask in host byte order to a CIDR prefix length.

size_t round_size (size_t align, size_t n)
 Rounds ``n'' up so that it matches the given alignment ``align''.

gint do_stat (const gchar *path, struct stat *buf)
 Wrapper for the stat() system call.

void ip_range_split (guint32 lower_ip, guint32 upper_ip, cidr_split_t cb, gpointer udata)
 Computes the set of CIDR ranges that make up the set of IPs between two boundary IPs, included.


Variables

gint do_errno

Define Documentation

#define BINARY_ARRAY_SORTED (  bs_array,
bs_type,
bs_field,
bs_cmp,
bs_field2str   ) 
 

Value:

G_STMT_START { \
    size_t bs_index; \
    size_t bs_size = G_N_ELEMENTS(bs_array); \
\
    for (bs_index = 1; bs_index < bs_size; bs_index++) { \
        const bs_type *prev = &bs_array[bs_index - 1]; \
        const bs_type *e = &bs_array[bs_index]; \
\
        if (bs_cmp(prev->bs_field, e->bs_field) >= 0) \
            g_error(STRINGIFY(bs_array) "[] unsorted (near item \"%s\")", \
                bs_field2str(e->bs_field)); \
    } \
} G_STMT_END
Ensure a table used for binary search is sorted.

bs_array is the (static) array to scan. bs_type is the type of bs_item bs_field is the field in the bs_item structure to compare. bs_cmp() is the comparison function to use between items bs_field2str is how one can stringify the bs_field.

Skip the first to have a previous element, tables with a single element are sorted anyway.

#define BINARY_SEARCH (  bs_type,
bs_key,
bs_size,
bs_cmp,
bs_get_key,
bs_found   ) 
 

Value:

G_STMT_START { \
    size_t bs_index, bs_j = 0, bs_k; \
    for (bs_k = (bs_size); bs_k != 0; bs_k >>= 1) { \
        bs_type bs_item; \
        gint bs_cmp_result; \
\
        bs_index = bs_j + (bs_k >> 1); \
        bs_item = bs_get_key(bs_index); \
        bs_cmp_result = bs_cmp(bs_item, bs_key); \
        if (0 == bs_cmp_result) {   \
            bs_found(bs_index); \
            break; \
        } else if (bs_cmp_result < 0) { \
            bs_j = bs_index + 1; \
            bs_k--; \
        } \
    } \
} G_STMT_END
Perform a binary search over an array.

bs_type is the type of bs_item bs_key is the key to lookup bs_size is the array length bs_cmp(bs_item, bs_key) is used to compare the key with the current item bs_get_key(bs_index) must return the key at bs_index bs_found(bs_index) is executed if bs_key is found

All local variables are prefixed with bs_ to prevent clashes with other visible variables.

#define clear_flags (  r,
f   )     (r &= ~(f))
 

#define CONST_STRLEN (  x   )     (sizeof(x) - 1)
 

#define delta_time (  a,
b   )     ((gint64) difftime((a), (b)))
 

#define EMPTY_STRING (  s   )     (NULL != (s) ? (s) : "")
 

#define G_N_ELEMENTS (  arr   )     (sizeof (arr) / sizeof ((arr)[0]))
 

#define g_string_printf   g_string_sprintf
 

#define g_strlcat   strlcat
 

#define g_strlcpy   strlcpy
 

#define GUID_HEX_SIZE   32 /**< Hexadecimal GUID representation */
 

Hexadecimal GUID representation.

#define GUID_RAW_SIZE   16 /**< Binary representation of 128 bits */
 

Binary representation of 128 bits.

#define IPV4_ADDR_BUFLEN   (sizeof "255.255.255.255")
 

#define IPV6_ADDR_BUFLEN   (sizeof "0001:0203:0405:0607:0809:1011:255.255.255.255")
 

#define NULL_STRING (  s   )     (NULL != (s) ? (s) : "(null)")
 

#define port_is_valid (  port   )     (port != 0)
 

#define set_flags (  r,
f   )     (r |= (f))
 

#define SIZE_FIELD_MAX   64 /**< Max size of sprintf-ed size quantity */
 

Max size of sprintf-ed size quantity.

#define TIMESTAMP_BUF_LEN   (sizeof "9999-12-31 23:59:61")
 

#define UINT16_DEC_BUFLEN   (sizeof "65535")
 

#define UINT16_HEX_BUFLEN   (sizeof "01234")
 

#define UINT32_DEC_BUFLEN   (sizeof "4294967295")
 

#define UINT32_HEX_BUFLEN   (sizeof "012345678")
 

#define UINT64_DEC_BUFLEN   (sizeof "18446744073709551615")
 

#define UINT64_HEX_BUFLEN   (sizeof "0123456789ABCDEF")
 

#define UINT8_DEC_BUFLEN   (sizeof "255")
 

#define UINT8_HEX_BUFLEN   (sizeof "FF")
 

#define USE_DIFFTIME
 

Typedef Documentation

typedef void(* cidr_split_t)(guint32 ip, guint bits, gpointer udata)
 

typedef guint16 flag_t
 

typedef void(* func_ptr_t)(void)
 

typedef void(* signal_handler_t)(gint signo)
 

Function Documentation

gint alnum2int_inline (  guchar  c  )  [inline, static]
 

Converts an alphanumeric char (0-9, A-Z, a-z) to an integer.

Parameters:
c the character to convert.
Returns:
0..9 for valid alphanumeric ASCII characters, -1 otherwise.

gint ascii_strcasecmp (  const gchar *  s1,
const gchar *  s2
) 
 

Same as strcasecmp() but only case-insensitive for ASCII characters.

gchar* ascii_strcasestr (  const gchar *  haystack,
const gchar *  needle
) 
 

Same as strstr() but case-insensitive with respect to ASCII characters.

void ascii_strlower (  gchar *  dst,
const gchar *  src
) 
 

Copies ``src'' to ``dst'', converting all ASCII upper-case characters to ASCII lower-case.

``dst'' and ``src'' may be identical but must not overlap otherwise.

gint ascii_strncasecmp (  const gchar *  s1,
const gchar *  s2,
size_t  len
) 
 

Same as strncasecmp() but only case-insensitive for ASCII characters.

G_GNUC_CONST WARN_UNUSED_RESULT gint ascii_tolower (  gint  c  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT gint ascii_toupper (  gint  c  )  [inline, static]
 

gchar* base32_sha1 (  const gchar *  base32  ) 
 

Convert base32 string into binary SHA1.

Parameters:
base32 a buffer holding SHA1_BASE32_SIZE or more bytes.
Returns:
Returns pointer to static data or NULL if the input wasn't a validly base32 encoded SHA1.

gchar* base32_to_guid (  const gchar *  base32  ) 
 

Decode the base32 representation of a GUID.

Returns:
pointer to static data, or NULL if the input was not valid base32.

gint canonize_path (  gchar *  dst,
const gchar *  path
) 
 

Creates the canonical representation of a path.

``dst'' and ``src'' may be identical but must not overlap otherwise.

Parameters:
dst the destination, must be sufficiently long.
path a NUL-terminated string representing the input path.
Returns:
zero on sucess, non-zero on failure.

TODO: Add overlap check.

G_GNUC_CONST WARN_UNUSED_RESULT gpointer cast_func_to_gpointer (  func_ptr_t  f  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT func_ptr_t cast_gpointer_to_func (  gconstpointer  p  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT gchar* cast_to_gchar_ptr (  gpointer  p  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT gconstpointer cast_to_gconstpointer (  gconstpointer  p  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT gpointer cast_to_gpointer (  gpointer  p  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT guchar* cast_to_guchar_ptr (  gpointer  p  )  [inline, static]
 

const gchar* compact_kb_size (  guint32  size  ) 
 

Returns:
a number of Kbytes in a compact readable form

const gchar* compact_rate (  guint64  rate  ) 
 

const gchar* compact_size (  guint64  size  ) 
 

gchar* compact_value (  gchar *  buf,
size_t  size,
guint64  v
) 
 

gboolean compat_is_superuser (  void   ) 
 

guint compat_max_fd (  void   ) 
 

gint compat_mkdir (  const gchar *  path,
mode_t  mode
) 
 

gpointer compat_page_align (  size_t  size  ) 
 

Allocates a page-aligned memory chunk.

Parameters:
size The size in bytes to allocate; will be rounded to the pagesize.

void compat_page_free (  gpointer  p,
size_t  size
) 
 

size_t compat_pagesize (  void   ) 
 

size_t concat_strings (  gchar *  dst,
size_t  size,
const gchar *  s,
... 
) 
 

Concatenates a variable number of NUL-terminated strings into ``dst''.

The resulting string will be NUL-terminated unless ``size'' is zero. The returned value is the length of the resulting string if ``dst'' had been large enough. If the returned value is equal to or greater than ``size'' the string is truncated. If ``size'' is zero, ``dst'' may be NULL to calculate the resulting string length.

The list of strings must be terminated by a NULL pointer. The first list element may be NULL in which case zero is returned.

Parameters:
dst the destination buffer.
size the number of bytes ``dst'' can hold.
s the first source string or NULL.
Returns:
the sum of the lengths of all passed strings.

gchar* control_escape (  const gchar *  s  ) 
 

Escape all ASCII control chars (except into the hexadecimal "\xhh" form.

Returns:
new escaped string, or the original string if no escaping occurred.

gint create_directory (  const gchar *  dir  ) 
 

Creates the given directory including sub-directories if necessary.

The path must be absolute.

Parameters:
dir the pathname of the directory to create.
Returns:
On success, zero is returned. On failure, -1 is returned and errno indicates the reason.

Bug:
FIXME: This might fail with ``fancy'' file permissions. The directories should be created from leaf to root instead of vice-versa.

gchar* data_hex_str (  const gchar *  data,
size_t  len
) 
 

Returns:
hexadecimal string representation of "small" binary buffer.
Note:
Buffer must be less than 40 chars, or only the first 40 chars are represented with a trailing "..." added to show it is incomplete.

gint dec2int_inline (  guchar  c  )  [inline, static]
 

Converts a decimal char (0-9) to an integer.

Parameters:
c the character to convert.
Returns:
0..9 for valid decimal ASCII characters, -1 otherwise.

G_GNUC_CONST WARN_UNUSED_RESULT gchar* deconstify_gchar (  const gchar *  p  )  [inline, static]
 

Cast a ``const gchar *'' to ``gchar *''.

This allows the compiler to print a diagnostic message if you accidently try to deconstify an incompatible type. A direct typecast would hide such a mistake.

G_GNUC_CONST WARN_UNUSED_RESULT gpointer deconstify_gpointer (  gconstpointer  p  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT guint32* deconstify_guint32 (  const guint32 *  p  )  [inline, static]
 

gint do_stat (  const gchar *  path,
struct stat *  buf
) 
 

Wrapper for the stat() system call.

void dump_hex (  FILE *  ,
const gchar *  ,
gconstpointer  ,
gint 
) 
 

Displays hex & ascii lines to the terminal (for debug) Displays the "title" then the characters in "s", # of bytes to print in "b".

gboolean file_exists (  const gchar *   ) 
 

Check for file existence.

gboolean filepath_exists (  const gchar *  dir,
const gchar *  file
) 
 

Check whether file given by its dirname and its basename exists.

gfloat force_range (  gfloat  val,
gfloat  min,
gfloat  max
) 
 

Enforce range boundaries on a given floating point number.

Parameters:
val The value to force within the range.
min The minimum value which val can be.
max The maximum value with val can be.
Returns:
The new value of val which will be between min and max.

WARN_UNUSED_RESULT const gchar* g_strip_context (  const gchar *  id,
const gchar *  val
)  [inline, static]
 

gchar* guid_base32_str (  const gchar *  guid  ) 
 

Converts GUID into its base32 representation, without the trailing padding.

Returns:
pointer to static data.

gchar* guid_hex_str (  const gchar *  guid  ) 
 

Returns:
hexadecimal string representing given GUID.

void guid_random_fill (  gchar *  xuid  ) 
 

Generate a new random GUID within given `xuid'.

gint hex2int (  guchar  c  ) 
 

Converts a hexadecimal char (0-9, A-F, a-f) to an integer.

Passing a character which is not a hexadecimal ASCII character causes an assertion failure.

Parameters:
c the hexadecimal ASCII character to convert.
Returns:
"0..15" for valid hexadecimal ASCII characters.

gint hex2int_inline (  guchar  c  )  [inline, static]
 

Converts a hexadecimal char (0-9, A-F, a-f) to an integer.

Parameters:
c the character to convert.
Returns:
0..15 for valid hexadecimal ASCII characters, -1 otherwise.

gchar* hex_escape (  const gchar *  name,
gboolean  strict
) 
 

Escape all non-printable chars into the hexadecimal "\xhh" form.

Returns:
new escaped string, or the original string if no escaping occurred.

gboolean hex_to_guid (  const gchar *  hexguid,
gchar *  guid
) 
 

Converts hexadecimal string into a GUID.

Parameters:
hexguid the hexadecimal representation to convert
guid the 16-byte array into which the decoded GUID is written to
Returns:
TRUE if OK.

gint highest_bit_set (  guint32  n  ) 
 

Determine the highest bit set in `n', -1 if value was 0.

const gchar* hostname_port_to_string (  const gchar *  hostname,
guint16  port
) 
 

size_t html_escape (  const gchar *  src,
gchar *  dst,
size_t  dst_size
) 
 

Copies the NUL-terminated string ``src'' to ``dst'' replacing all characters which are reserved in HTML with a replacement string.

Parameters:
src a NUL-terminated string.
dst the destination buffer, may be NULL if ``size'' is zero.
dst_size the size in bytes of the destination buffer.
Returns:
the length in bytes of resulting string assuming size was sufficiently large.

const gchar* ip_port_to_string (  guint32  ,
guint16 
) 
 

void ip_range_split (  guint32  lower_ip,
guint32  upper_ip,
cidr_split_t  cb,
gpointer  udata
) 
 

Computes the set of CIDR ranges that make up the set of IPs between two boundary IPs, included.

For instance, for the range 2.0.0.0 - 2.138.24.150, we have:

2.0.0.0/9, 2.128.0.0/13, 2.136.0.0/15, 2.138.0.0/20, 2.138.16.0/21, 2.138.24.0/25, 2.138.24.128/28, 2.138.24.144/30, 2.138.24.148, 2.138.24.149 and 2.138.24.150.

For each identified CIDR range, invoke the supplied callback, along with the trailing user-supplied `udata' pointer.

Parameters:
lower_ip the lower-bound IP
upper_ip the upper-bound IP
cb the callback, invoked as callback(ip, bits, udata)
udata the trailing parameter passed as-is to the callbacks

const gchar* ip_to_string (  guint32   ) 
 

const gchar* ip_to_string2 (  guint32   ) 
 

size_t ip_to_string_buf (  guint32  ip,
gchar *  buf,
size_t  size
) 
 

const gchar* ipv6_to_string (  const guint8 *  ipv6  ) 
 

Prints the IPv6 address ``ipv6'' to a static buffer.

Parameters:
ipv6 the IPv6 address; must point to a buffer of 16 bytes.
Returns:
a pointer to a static buffer holding a NUL-terminated string representing the given IPv6 address.

size_t ipv6_to_string_buf (  const guint8 *  ipv6,
gchar *  dst,
size_t  size
) 
 

gboolean is_absolute_path (  const char *   ) 
 

Check whether path is an absolute path.

G_GNUC_CONST WARN_UNUSED_RESULT gboolean is_ascii_alnum (  gint  c  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT gboolean is_ascii_alpha (  gint  c  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT gboolean is_ascii_blank (  gint  c  )  [inline, static]
 

ctype-like functions that allow only ASCII characters whereas the locale would allow others.

The parameter doesn't have to be casted to (unsigned char) because these functions return false for everything out of [0..127].

GLib 2.x has similar macros/functions but defines only a subset.

G_GNUC_CONST WARN_UNUSED_RESULT gboolean is_ascii_cntrl (  gint  c  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT gboolean is_ascii_digit (  gint  c  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT gboolean is_ascii_graph (  gint  c  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT gboolean is_ascii_lower (  gint  c  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT gboolean is_ascii_print (  gint  c  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT gboolean is_ascii_punct (  gint  c  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT gboolean is_ascii_space (  gint  c  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT gboolean is_ascii_upper (  gint  c  )  [inline, static]
 

G_GNUC_CONST WARN_UNUSED_RESULT gboolean is_ascii_xdigit (  gint  c  )  [inline, static]
 

gboolean is_directory (  const gchar *   ) 
 

Check whether path is a directory.

G_GNUC_CONST gboolean is_pow2 (  guint32  value  )  [inline, static]
 

Checks whether the given value is a power of 2.

Parameters:
value a 32-bit integer
Returns:
TRUE if ``value'' is a power of 2. Otherwise FALSE.

gboolean is_printable (  const gchar *  buf,
gint  len
) 
 

Check whether buffer contains printable data, suitable for "%s" printing.

If not, consider dump_hex().

gboolean is_regular (  const gchar *   ) 
 

Check whether path points to a regular file.

gchar* is_strcaseprefix (  const gchar *  str,
const gchar *  prefix
) 
 

Checks whether ``prefix'' is a prefix of ``str'' performing an case-insensitive (ASCII only) check.

Maybe skip_caseprefix() would be a better name.

Parameters:
str a NUL-terminated string
prefix a NUL-terminated string
Returns:
NULL, if ``prefix'' is not a prefix of ``str''. Otherwise, a pointer to the first character in ``str'' after the prefix.

gchar* is_strprefix (  const gchar *  str,
const gchar *  prefix
) 
 

Checks whether ``prefix'' is a prefix of ``str''.

Maybe skip_prefix() would be a better name.

Parameters:
str a NUL-terminated string
prefix a NUL-terminated string
Returns:
NULL, if ``prefix'' is not a prefix of ``str''. Otherwise, a pointer to the first character in ``str'' after the prefix.

gboolean is_symlink (  const gchar *   ) 
 

Check whether path is a symbolic link.

const gchar* lazy_string_to_printf_escape (  const gchar *  src  ) 
 

Escapes a string so that it can be used careless with the POSIX printf tool.

Therefore it's absolutely paranoid and escapes everything but ASCII alphanumerics, dots, hyphen and underscores.

Note:
Hex sequences are always two digits long, so "\xAAA" is the same as "\xAA" "A". In C this not necessarily true and could be understood as a wide-char sequence.
Parameters:
src The string to escape.
Returns:
The escaped string. MUST NOT be freed.

const gchar* local_hostname (  void   ) 
 

Returns:
local host name, as pointer to static data.

void locale_strlower (  gchar *  dst,
const gchar *  src
) 
 

Copies ``src'' to ``dst'', converting all upper-case characters to lower-case.

``dst'' and ``src'' may point to the same object. The conversion depends on the current locale.

gchar* make_pathname (  const gchar *  dir,
const gchar *  file
) 
 

Create new pathname from the concatenation of the dirname and the basename of the file.

A directory separator is insert, unless "dir" already ends with one or "filename" starts with one.

Parameters:
dir The directory path.
file The filename.
Returns:
A newly allocated string.

void misc_init (  void   ) 
 

G_GNUC_CONST WARN_UNUSED_RESULT guint8 netmask_to_cidr (  guint32  netmask  )  [inline, static]
 

Converts the given IPv4 netmask in host byte order to a CIDR prefix length.

No checks are performed whether the netmask is proper and if it's not the result is unspecified.

Parameters:
netmask an IPv4 netmask in host byte order.
Returns:
The CIDR prefix length (0..32).

guint32 next_pow2 (  guint32  n  ) 
 

Returns:
the closest power of two greater or equal to `n'. next_pow2(0) and next_pow2(0x8.......) return 0.

gboolean parse_ipv6_addr (  const gchar *  s,
uint8_t *  dst,
const gchar **  endptr
) 
 

gint parse_major_minor (  const gchar *  src,
gchar const **  endptr,
guint *  major,
guint *  minor
) 
 

guint16 parse_uint16 (  const gchar *  ,
gchar const **  ,
guint  ,
gint * 
) 
 

guint32 parse_uint32 (  const gchar *  ,
gchar const **  ,
guint  ,
gint * 
) 
 

guint64 parse_uint64 (  const gchar *  ,
gchar const **  ,
guint  ,
gint * 
) 
 

void random_init (  void   ) 
 

Initialize random number generator.

guint32 random_value (  guint32  max  ) 
 

Returns:
random value between (0..max).

size_t round_size (  size_t  align,
size_t  n
)  [inline, static]
 

Rounds ``n'' up so that it matches the given alignment ``align''.

signal_handler_t set_signal (  gint  signo,
signal_handler_t  handler
) 
 

Installs a signal handler.

The signal handler is not reset to the default handler after delivery. If the signal is SIGALRM, the handler is installed so that interrupted system calls fail with EINTR. Handlers for other all signals are installed so that interrupted system calls are restarted instead.

Parameters:
signo the signal number.
handler the signal handler to install.
Returns:
the previous signal handler or SIG_ERR on failure.

gchar* sha1_base32 (  const gchar *  sha1  ) 
 

Convert binary SHA1 into a base32 string.

Returns:
pointer to static data.

gchar* short_filename (  gchar *  fullname  ) 
 

Determine stripped down path, removing SRC_PREFIX if present.

Returns:
pointer within supplied string.

const gchar* short_html_size (  guint64  size  ) 
 

Like short_size() but with unbreakable space between the digits and unit.

const gchar* short_kb_size (  guint64  size  ) 
 

const gchar* short_rate (  guint64  rate  ) 
 

const gchar* short_size (  guint64  size  ) 
 

gchar* short_time (  gint  t  ) 
 

Returns:
time spent in seconds in a consise short readable form

gchar* short_uptime (  gint  s  ) 
 

Alternate time formatter for uptime.

gchar* short_value (  gchar *  buf,
size_t  size,
guint64  v
) 
 

WARN_UNUSED_RESULT gchar* skip_ascii_blanks (  const gchar *  s  )  [inline, static]
 

Skips over all ASCII blank characters starting at ``s''.

Returns:
a pointer to the first non-blank character starting from s.

WARN_UNUSED_RESULT gchar* skip_ascii_spaces (  const gchar *  s  )  [inline, static]
 

Skips over all ASCII space characters starting at ``s''.

Returns:
a pointer to the first non-space character starting from s.

gint str_chomp (  gchar *  str,
gint  len
) 
 

Remove antepenultimate char of string if it is a "\r" followed by "\n".

Remove final char of string if it is a "\n" or "\r". If len is 0, compute it.

Returns:
new string length.

gint strcasecmp_delimit (  const gchar *  a,
const gchar *  b,
const gchar *  delimit
) 
 

Compare two strings case-insensitive up to the specified delimiters.

gint strcmp_delimit (  const gchar *  a,
const gchar *  b,
const gchar *  delimit
) 
 

Compare two strings case-senstive up to the specified delimiters.

guint32 string_to_ip (  const gchar *  s  ) 
 

Returns:
0 if ``s'' is not a valid IPv4 address. Otherwise, the parsed IPv4 address in host byte order.

gboolean string_to_ip_and_mask (  const gchar *  str,
guint32 *  ip,
guint32 *  netmask
) 
 

Extracts the IP address into `ip' and the netmask into `netmask'.

Returns:
whether the supplied string represents a valid ip/mask combination.
Accepted forms: "a.b.c.d" implies /32 "a.b.c.d/e" whereas e [1..32] "a.b.c.d/w.x.y.z"

If the IP address or the netmask is zero, the function will return FALSE.

gboolean string_to_ip_port (  const gchar *  s,
guint32 *  ip_ptr,
guint16 *  port_ptr
) 
 

Decompiles ip:port into ip and port.

Leading spaces are ignored.

Returns:
TRUE if it parsed correctly, FALSE otherwise.

gboolean string_to_ip_strict (  const gchar *  s,
guint32 *  addr,
const gchar **  endptr
) 
 

A strict string to IP address conversion; when other stuff from misc.[ch] is not sufficient.

Returns:
TRUE if ``s'' pointed to a string representation of an IPv4 address, otherwise FALSE.
If successful, ``*addr'' will be set to the IPv4 address in NATIVE byte order and ``*endptr'' will point to the character after the IPv4 address. ``addr'' and ``endptr'' may be NULL.

size_t strlcat (  gchar *  dst,
const gchar *  src,
size_t  dst_size
) 
 

size_t strlcpy (  gchar *  dst,
const gchar *  src,
size_t  dst_size
) 
 

Needs to be defined if we are not using Glib 2.

G_GNUC_CONST guint32 swap_guint32 (  guint32  i  )  [inline, static]
 

Swap endianness of a guint32.

Parameters:
i the guint32 to swap
Returns:
the value of i after swapping its byte order.

size_t time_locale_to_string_buf (  time_t  t,
gchar *  dst,
size_t  size
) 
 

Convert time (without the date) to a human-readable string using the time representation of the current locale.

Parameters:
t time to convert.
dst buffer to hold the resulting string.
size the size of the dst buffer.
Returns:
length of the created string.

const gchar* timestamp_rfc1123_to_string (  time_t  date  ) 
 

Convert time to RFC-1123 style date.

Returns:
pointer to static data.

const gchar* timestamp_rfc822_to_string (  time_t  date  ) 
 

Convert time to RFC-822 style date.

Returns:
pointer to static data.

const gchar* timestamp_rfc822_to_string2 (  time_t  date  ) 
 

Same as date_to_rfc822_gchar(), to be able to use the two in the same printf() line.

const gchar* timestamp_to_string (  time_t  date  ) 
 

Convert time to ISO 8601 date plus time, e.g.

"2005-11-10 20:21:57".

Returns:
pointer to static data.

size_t timestamp_to_string_buf (  time_t  date,
gchar *  dst,
size_t  size
) 
 

Convert time to ISO 8601 date plus time, e.g.

"2002-06-09 14:54:42".

Returns:
The length of the created string.

const gchar* timestamp_utc_to_string (  time_t  date  ) 
 

Convert time to an ISO 8601 timestamp, e.g.

"2002-06-09T14:54:42Z".

Returns:
pointer to static data.

const gchar* uint32_to_string (  guint32  v  ) 
 

size_t uint32_to_string_buf (  guint64  v,
gchar *  dst,
size_t  size
) 
 

const gchar* uint64_to_string (  guint64  v  ) 
 

const gchar* uint64_to_string2 (  guint64  v  ) 
 

size_t uint64_to_string_buf (  guint64  v,
gchar *  dst,
size_t  size
) 
 

char* unique_filename (  const gchar *  path,
const gchar *  file,
const gchar *  ext
) 
 

Determine unique filename for `file' in `path', with optional trailing extension `ext'.

If no `ext' is wanted, one must supply an empty string.

Returns:
the chosen unique complete filename as a pointer which must be freed.

size_t w_concat_strings (  gchar **  dst_ptr,
const gchar *  first,
... 
) 
 

Concatenates a variable number of NUL-terminated strings into buffer which will be allocated using walloc().

The list of strings must be terminated by a NULL pointer. The first list element may be NULL in which case 1 is returned.

Parameters:
dst_ptr if not NULL, it will point to the allocated buffer.
first the first source string or NULL.
Returns:
The sum of the lengths of all passed strings plus 1 for the the trailing NUL. Use this as size argument for wfree() to release the allocated buffer.

Variable Documentation

gint do_errno
 

Generated on Sun Feb 12 10:50:04 2006 for Gtk-Gnutella by doxygen 1.3.6