libosmocore 0.9.6-23.20170220git32ee5af8.fc42
Osmocom core library
Loading...
Searching...
No Matches
General-purpose utility functions

Files

file  defs.h
 General definitions that are meant to be included from header files.
 
file  panic.h
 
file  utils.h
 
file  loggingrb.c
 
file  panic.c
 Routines for panic handling.
 
file  utils.c
 

Data Structures

struct  value_string
 A mapping between human-readable string and numeric value. More...
 

Macros

#define OSMO_GNUC_PREREQ(maj, min)
 Check for gcc and version.
 
#define OSMO_DEPRECATED(text)
 Set the deprecated attribute with a message.
 
#define ARRAY_SIZE(x)
 Determine number of elements in an array of static size.
 
#define OSMO_MAX(a, b)
 Return the maximum of two specified values.
 
#define OSMO_MIN(a, b)
 Return the minimum of two specified values.
 
#define OSMO_STRINGIFY(x)
 Stringify the contents of a macro, e.g. a port number.
 
#define OSMO_VALUE_STRING(x)
 Make a value_string entry from an enum value name.
 
#define osmo_static_assert(exp, name)
 
#define OSMO_SNPRINTF_RET(ret, rem, offset, len)
 
#define OSMO_ASSERT(exp)
 

Typedefs

typedef void(* osmo_panic_handler_t) (const char *fmt, va_list args)
 panic handler callback function type
 

Functions

void osmo_panic (const char *fmt,...)
 Terminate the current program with a panic.
 
void osmo_set_panic_handler (osmo_panic_handler_t h)
 Set the panic handler.
 
const char * get_value_string (const struct value_string *vs, uint32_t val)
 get human-readable string for given value
 
const char * get_value_string_or_null (const struct value_string *vs, uint32_t val)
 get human-readable string or NULL for given value
 
int get_string_value (const struct value_string *vs, const char *str)
 get numeric value for given human-readable string
 
char osmo_bcd2char (uint8_t bcd)
 Convert BCD-encoded digit into printable character.
 
uint8_t osmo_char2bcd (char c)
 Convert number in ASCII to BCD value.
 
int osmo_hexparse (const char *str, uint8_t *b, int max_len)
 Parse a string containing hexadecimal digits.
 
char * osmo_ubit_dump (const uint8_t *bits, unsigned int len)
 Convert a sequence of unpacked bits to ASCII string.
 
char * osmo_hexdump (const unsigned char *buf, int len)
 Convert binary sequence to hexadecimal ASCII string.
 
char * osmo_hexdump_nospc (const unsigned char *buf, int len)
 Convert binary sequence to hexadecimal ASCII string.
 
char * osmo_osmo_hexdump_nospc (const unsigned char *buf, int len) __attribute__((__deprecated__))
 
void osmo_str2lower (char *out, const char *in)
 Convert an entire string to lower case.
 
void osmo_str2upper (char *out, const char *in)
 Convert an entire string to upper case.
 
static void osmo_talloc_replace_string (void *ctx, char **dst, const char *newstr)
 
int osmo_constant_time_cmp (const uint8_t *exp, const uint8_t *rel, const int count)
 Wishful thinking to generate a constant time compare.
 
uint64_t osmo_decode_big_endian (const uint8_t *data, size_t data_len)
 Generic retrieval of 1..8 bytes as big-endian uint64_t.
 
uint8_t * osmo_encode_big_endian (uint64_t value, size_t data_len)
 Generic big-endian encoding of big endian number up to 64bit.
 
size_t osmo_strlcpy (char *dst, const char *src, size_t siz)
 Copy a C-string into a sized buffer.
 
int osmo_macaddr_parse (uint8_t *out, const char *in)
 Parse a MAC address from human-readable notation This function parses an ethernet MAC address in the commonly-used hex/colon notation (00:00:00:00:00:00) and generates the binary representation from it.
 
int osmo_get_macaddr (uint8_t *mac_out, const char *dev_name)
 Obtain the MAC address of a given network device.
 
static void osmo_panic_default (const char *fmt, va_list args)
 
static char * _osmo_hexdump (const unsigned char *buf, int len, char *delim)
 
char alias ("osmo_hexdump_nospc")))
 

Variables

static osmo_panic_handler_t osmo_panic_handler = (void*)0
 
static char namebuf [255]
 
static char hexd_buff [4096]
 
static const char hex_chars [] = "0123456789abcdef"
 

Detailed Description

Macro Definition Documentation

◆ ARRAY_SIZE

#define ARRAY_SIZE ( x)
Value:
(sizeof(x) / sizeof((x)[0]))

Determine number of elements in an array of static size.

Referenced by log_init(), msgb_hexdump(), and osmo_encode_big_endian().

◆ OSMO_ASSERT

#define OSMO_ASSERT ( exp)
Value:
if (!(exp)) { \
fprintf(stderr, "Assert failed %s %s:%d\n", #exp, __BASE_FILE__, __LINE__); \
osmo_generate_backtrace(); \
abort(); \
}

Helper macro to terminate when an assertion failes

Parameters
[in]expPredicate to verify This function will generate a backtrace and terminate the program if the predicate evaluates to false (0).

Referenced by _osmo_fsm_inst_dispatch(), log_parse_category_mask(), and osmo_encode_big_endian().

◆ OSMO_GNUC_PREREQ

#define OSMO_GNUC_PREREQ ( maj,
min )
Value:
0

Check for gcc and version.

Note
Albeit glibc provides a features.h file that contains a similar definition (__GNUC_PREREQ), this definition has been copied from there to have it available with other libraries, too.
Returns
!= 0 iff gcc is used and it's version is at least maj.min.

◆ OSMO_MAX

#define OSMO_MAX ( a,
b )
Value:
((a) >= (b) ? (a) : (b))

Return the maximum of two specified values.

◆ OSMO_MIN

#define OSMO_MIN ( a,
b )
Value:
((a) >= (b) ? (b) : (a))

Return the minimum of two specified values.

◆ OSMO_SNPRINTF_RET

#define OSMO_SNPRINTF_RET ( ret,
rem,
offset,
len )
Value:
do { \
len += ret; \
if (ret > rem) \
ret = rem; \
offset += ret; \
rem -= ret; \
} while (0)

◆ osmo_static_assert

#define osmo_static_assert ( exp,
name )
Value:
typedef int dummy##name [(exp) ? 1 : -1] __attribute__((__unused__));

◆ OSMO_STRINGIFY

#define OSMO_STRINGIFY ( x)
Value:
#x

Stringify the contents of a macro, e.g. a port number.

◆ OSMO_VALUE_STRING

#define OSMO_VALUE_STRING ( x)
Value:
{ x, OSMO_STRINGIFY(x) }
#define OSMO_STRINGIFY(x)
Stringify the contents of a macro, e.g. a port number.
Definition utils.h:19

Make a value_string entry from an enum value name.

Function Documentation

◆ get_string_value()

int get_string_value ( const struct value_string * vs,
const char * str )

get numeric value for given human-readable string

Parameters
[in]vsArray of value_string tuples
[in]strhuman-readable string
Returns
numeric value (>0) or negative numer in case of error

References value_string::value.

Referenced by log_parse_level().

◆ get_value_string()

const char * get_value_string ( const struct value_string * vs,
uint32_t val )

get human-readable string for given value

Parameters
[in]vsArray of value_string tuples
[in]valValue to be converted
Returns
pointer to human-readable string

If val is found in vs, the array's string entry is returned. Otherwise, an "unknown" string containing the actual value is composed in a static buffer that is reused across invocations.

References get_value_string_or_null().

Referenced by log_level_str(), and osmo_fsm_event_name().

◆ get_value_string_or_null()

const char * get_value_string_or_null ( const struct value_string * vs,
uint32_t val )

get human-readable string or NULL for given value

Parameters
[in]vsArray of value_string tuples
[in]valValue to be converted
Returns
pointer to human-readable string or NULL if val is not found

References value_string::str.

Referenced by get_value_string().

◆ osmo_bcd2char()

char osmo_bcd2char ( uint8_t bcd)

Convert BCD-encoded digit into printable character.

Parameters
[in]bcdA single BCD-encoded digit
Returns
single printable character

◆ osmo_char2bcd()

uint8_t osmo_char2bcd ( char c)

Convert number in ASCII to BCD value.

Parameters
[in]cASCII character
Returns
BCD encoded value of character

◆ osmo_constant_time_cmp()

int osmo_constant_time_cmp ( const uint8_t * exp,
const uint8_t * rel,
const int count )

Wishful thinking to generate a constant time compare.

Parameters
[in]expExpected data
[in]relComparison value
[in]countNumber of bytes to compare
Returns
1 in case exp equals rel; zero otherwise

Compare count bytes of exp to rel. Return 0 if they are identical, 1 otherwise. Do not return a mismatch on the first mismatching byte, but always compare all bytes, regardless. The idea is that the amount of matching bytes cannot be inferred from the time the comparison took.

◆ osmo_decode_big_endian()

uint64_t osmo_decode_big_endian ( const uint8_t * data,
size_t data_len )

Generic retrieval of 1..8 bytes as big-endian uint64_t.

Parameters
[in]dataInput data as byte-array
[in]data_lenLength of data in octets
Returns
uint64_t of data interpreted as big-endian

This is like osmo_load64be_ext, except that if data_len is less than sizeof(uint64_t), the data is interpreted as the least significant bytes (osmo_load64be_ext loads them as the most significant bytes into the returned uint64_t). In this way, any integer size up to 64 bits can be decoded conveniently by using sizeof(), without the need to call specific numbered functions (osmo_load16, 32, ...).

◆ osmo_encode_big_endian()

uint8_t * osmo_encode_big_endian ( uint64_t value,
size_t data_len )

Generic big-endian encoding of big endian number up to 64bit.

Parameters
[in]valueunsigned integer value to be stored
[in]data_lennumber of octets
Returns
static buffer containing big-endian stored value

This is like osmo_store64be_ext, except that this returns a static buffer of the result (for convenience, but not threadsafe). If data_len is less than sizeof(uint64_t), only the least significant bytes of value are encoded.

References ARRAY_SIZE, and OSMO_ASSERT.

◆ osmo_get_macaddr()

int osmo_get_macaddr ( uint8_t * mac_out,
const char * dev_name )

Obtain the MAC address of a given network device.

Parameters
[out]mac_outpointer to caller-allocated buffer of 6 bytes
[in]dev_namestring name of the network device
Returns
0 in case of success; negative otherwise

◆ osmo_hexdump()

char * osmo_hexdump ( const unsigned char * buf,
int len )

Convert binary sequence to hexadecimal ASCII string.

Parameters
[in]bufpointer to sequence of bytes
[in]lenlength of buf in number of bytes
Returns
pointer to zero-terminated string

This function will print a sequence of bytes as hexadecimal numbers, adding one space character between each byte (e.g. "1a ef d9")

Referenced by msgb_hexdump().

◆ osmo_hexdump_nospc()

char * osmo_hexdump_nospc ( const unsigned char * buf,
int len )

Convert binary sequence to hexadecimal ASCII string.

Parameters
[in]bufpointer to sequence of bytes
[in]lenlength of buf in number of bytes
Returns
pointer to zero-terminated string

This function will print a sequence of bytes as hexadecimal numbers, without any space character between each byte (e.g. "1aefd9")

◆ osmo_hexparse()

int osmo_hexparse ( const char * str,
uint8_t * b,
int max_len )

Parse a string containing hexadecimal digits.

Parameters
[in]strstring containing ASCII encoded hexadecimal digits
[out]boutput buffer
[in]max_lenmaximum space in output buffer
Returns
number of parsed octets, or -1 on error

◆ osmo_macaddr_parse()

int osmo_macaddr_parse ( uint8_t * out,
const char * in )

Parse a MAC address from human-readable notation This function parses an ethernet MAC address in the commonly-used hex/colon notation (00:00:00:00:00:00) and generates the binary representation from it.

Parameters
[out]outpointer to caller-allocated buffer of 6 bytes
[in]inpointer to input data as string with hex/colon notation

◆ osmo_panic()

void osmo_panic ( const char * fmt,
... )
extern

Terminate the current program with a panic.

You can call this function in case some severely unexpected situation is detected and the program is supposed to terminate in a way that reports the fact that it terminates.

The application can register a panic handler function using osmo_set_panic_handler. If it doesn't, a default panic handler function is called automatically.

The default function on most systems will generate a backtrace and then abort() the process.

◆ osmo_set_panic_handler()

void osmo_set_panic_handler ( osmo_panic_handler_t h)
extern

Set the panic handler.

Parameters
[in]hNew panic handler function

This changes the panic handling function from the currently active function to a new call-back function supplied by the caller.

◆ osmo_str2lower()

void osmo_str2lower ( char * out,
const char * in )

Convert an entire string to lower case.

Parameters
[out]outoutput string, caller-allocated
[in]ininput string

◆ osmo_str2upper()

void osmo_str2upper ( char * out,
const char * in )

Convert an entire string to upper case.

Parameters
[out]outoutput string, caller-allocated
[in]ininput string

◆ osmo_strlcpy()

size_t osmo_strlcpy ( char * dst,
const char * src,
size_t siz )

Copy a C-string into a sized buffer.

Parameters
[in]srcsource string
[out]dstdestination string
[in]sizsize of the dst buffer
Returns
length of src

Copy at most siz bytes from src to dst, ensuring that the result is NUL terminated. The NUL character is included in siz, i.e. passing the actual sizeof(*dst) is correct.

◆ osmo_talloc_replace_string()

static void osmo_talloc_replace_string ( void * ctx,
char ** dst,
const char * newstr )
inlinestatic

duplicate a string using talloc and release its prior content (if any)

Parameters
[in]ctxTalloc context to use for allocation
[out]dstpointer to string, will be updated with ptr to new string
[in]newstrString that will be copieed to newly allocated string

◆ osmo_ubit_dump()

char * osmo_ubit_dump ( const uint8_t * bits,
unsigned int len )

Convert a sequence of unpacked bits to ASCII string.

Parameters
[in]bitsA sequence of unpacked bits
[in]lenLength of bits