#include <words.h>
#include <stdlib.h>
#include <stdarg.h>

Macros
#define	_ext extern

#define	_sn_cpy_str_safe(_dst, _src) sn_cpy_str_safe( _dst, sizeof( _dst ), _src )

Functions
static __mbg_inline bool	mbg_buffer_specs_valid (char *s, size_t max_len)
	Check if the buffer plus size parameters passed to a function are valid. More...

static __mbg_inline int	mbg_chk_snprint_results (size_t n, char *s, size_t max_len)
	Check the results of an snprintf()-like function. More...

int	vsnprintf_safe (char s, size_t max_len, const char fmt, va_list args)
	A portable, safe implementation of vsnprintf() More...

int	snprintf_safe (char s, size_t max_len, const char fmt,...)
	A portable, safe implementation of snprintf() More...

char *	strncpy_safe (char dst, const char src, size_t max_len)
	A portable, safe implementation of strncpy() More...

int	sn_cpy_str_safe (char dst, size_t max_len, const char src)
	A function to copy a string safely, returning the number of characters copied. More...

int	sn_cpy_char_safe (char *dst, size_t max_len, char c)
	A function to copy a character safely to a string buffer. More...

void	trim_trailing_whitespace (char *s)
	Trim whitespace at the end of a string. More...

void	trim_leading_whitespace (char *s)
	Trim whitespace at the beginning of a string. More...

void	trim_whitespace (char *s)
	Trim both leading and trailing whitespace from a string. More...

void	mbg_memcpy (void dst, const void src, size_t n_bytes)
	Copy array of bytes starting at beginning of buffer. More...

void	mbg_memcpy_reversed (void dst, const void src, size_t n_bytes)
	Copy an array of bytes in reversed order, starting at end of buffer. More...

Variables
const char *	str_not_avail

Macro Definition Documentation

◆ _ext

#define _ext extern

Definition at line 53 of file str_util.h.

◆ _sn_cpy_str_safe

#define _sn_cpy_str_safe	(	_dst,
		_src
	)	sn_cpy_str_safe( _dst, sizeof( _dst ), _src )

Definition at line 152 of file str_util.h.

Function Documentation

◆ mbg_buffer_specs_valid()

static __mbg_inline bool mbg_buffer_specs_valid	(	char *	s,
		size_t	max_len
	)

static

Check if the buffer plus size parameters passed to a function are valid.

This function can be used to check parameters that have been passed to another function to specify an output buffer to be filled.

If no buffer has been specified, or the size of the buffer which eventually remains after a previous operation is 0 or even less than 0 then no data can be placed in the buffer.

Parameters

[in]	s	The address of the specified buffer
[in]	max_len	The size of the specified buffer.

Returns: true if the buffer address is not NULL and the size is > 0, else false.

Definition at line 88 of file str_util.h.

Referenced by mbg_chk_snprint_results(), mbg_kdd_vsnprintf(), and vsnprintf_safe().

◆ mbg_chk_snprint_results()

static __mbg_inline int mbg_chk_snprint_results	(	size_t	n,
		char *	s,
		size_t	max_len
	)

static

Check the results of an snprintf()-like function.

Implementations of snprintf()-like functions may behave differently and badly if the specified output buffer is too small. The exact behavior depends on the runtime library shipped with a specific build environment for a specific operating system, the version of that runtime library, and may even differ depending on whether kernel mode or user mode code is compiled.

This function can be called after any snprintf()-like function to make sure that a valid buffer is always 0-terminated, and the number returned to indicate how many bytes have been written to the buffer is never less than 0, and never exceeds the real size of the buffer.

Parameters

[in]	n	The return code from an snprintf()-like function that has been called before.
[in]	s	The address of the buffer that had been passed to the snprintf()-like function.
[in]	max_len	The size of the specified buffer that had been passed to the snprintf()-like function.

Returns: The real number of bytes that had been written to the buffer.

See also: vsnprintf_safe; mbg_kdd_vsnprintf; mbg_buffer_specs_valid

Definition at line 123 of file str_util.h.

References _int_from_size_t, and mbg_buffer_specs_valid().

Referenced by mbg_kdd_vsnprintf(), and vsnprintf_safe().

◆ mbg_memcpy()

void mbg_memcpy	(	void *	dst,
		const void *	src,
		size_t	n_bytes
	)

Copy array of bytes starting at beginning of buffer.

Can be used if the destination address is in the same buffer in front of the source address. Even though you would expect that memcpy() would also work for this properly, we have seen cases where it didn't, and only memmove() worked correctly. Anyway, we try to avoid the overhead of memmove().

Parameters

[out]	dst	Destination address behind the source address
[in]	src	Source address
[in]	n_bytes	Number of bytes to copy

See also: mbg_memcpy_reversed

Definition at line 412 of file str_util.c.

Referenced by mbgextio_rcv_msg_unlocked().

◆ mbg_memcpy_reversed()

void mbg_memcpy_reversed	(	void *	dst,
		const void *	src,
		size_t	n_bytes
	)

Copy an array of bytes in reversed order, starting at end of buffer.

Can be used if the destination address is in the same buffer behind the source address, so the source address would be overwritten by a normal memcpy().

Parameters

[out]	dst	Destination address behind the source address
[in]	src	Source address
[in]	n_bytes	Number of bytes to copy

See also: mbg_memcpy

Definition at line 438 of file str_util.c.

◆ sn_cpy_char_safe()

int sn_cpy_char_safe	(	char *	dst,
		size_t	max_len,
		char	c
	)

A function to copy a character safely to a string buffer.

This basically works like sn_cpy_str_safe but expects a character to be copied to the destination buffer. Appends a terminating 0 to the string buffer and returns the number of characters copied to the destination buffer, usually 0 or 1.

Parameters

[out]	dst	Pointer to the output buffer
[in]	max_len	Size of the output buffer for 0-terminated string
[in]	c	Character to be copied to the destination buffer

Returns: Number of characters copied to the destination buffer, without the terminating 0

See also: vsnprintf_safe; snprintf_safe; strncpy_safe; sn_cpy_str_safe

Definition at line 306 of file str_util.c.

References _int_from_size_t, and do_str_copy_safe().

Referenced by get_tz_name(), pcps_date_time_str(), pcps_str_tm_gps_date_time(), snprint_ctry_dt(), snprint_ctry_dt_short(), snprint_ctry_tm(), snprint_ctry_tm_long(), and snprint_ctry_tm_short().

◆ sn_cpy_str_safe()

int sn_cpy_str_safe	(	char *	dst,
		size_t	max_len,
		const char *	src
	)

A function to copy a string safely, returning the number of characters copied.

This basically works like strncpy_safe but instead of a pointer to the destination buffer it returns the number of characters copied to the destination buffer.

Parameters

[out]	dst	Pointer to the output buffer
[in]	max_len	Size of the output buffer for 0-terminated string
[in]	src	Pointer to the input buffer

Returns: Number of characters copied to the destination buffer

See also: vsnprintf_safe; snprintf_safe; strncpy_safe; sn_cpy_char_safe

Definition at line 276 of file str_util.c.

References _int_from_size_t, and do_str_copy_safe().

Referenced by do_mbgcmptime(), do_str_pcps_hr_date_time(), get_tz_name(), mbg_open_device_by_name(), mbg_str_dev_name(), mbg_str_pcps_hr_date(), mbg_str_pcps_hr_time(), mbg_strncpy(), mbgextio_get_cmd_name(), mbgextio_setup_receiver_info(), pcps_date_time_str(), pcps_str_tm_gps_date_time(), setup_asic_features(), setup_device_type_name(), sn_printf_timespec(), snprint_utc_offs(), and swap_pos_doubles().

◆ snprintf_safe()

int snprintf_safe	(	char *	s,
		size_t	max_len,
		const char *	fmt,
			...
	)

A portable, safe implementation of snprintf()

For a detailed description see vsnprintf_safe

Parameters

[out]	s	The string buffer to be filled
[in]	max_len	Size of the output buffer for 0-terminated string
[in]	fmt	Format string according to subsequent parameters
[in]	...	Variable argument list according to the format string

Returns: Number of characters written to the output buffer, except the terminating 0

See also: vsnprintf_safe; strncpy_safe; sn_cpy_str_safe; sn_cpy_char_safe

Definition at line 156 of file str_util.c.

References vsnprintf_safe().

Referenced by __to_iso_frac(), do_mbgcmptime(), get_ip4_gateway(), get_tz_name(), intv_str(), mbg_dev_fn_from_dev_idx(), mbg_get_all_net_cfg_info(), mbg_get_all_net_status_info(), mbg_open_device_by_param(), mbg_open_device_by_param_chk(), mbg_program_info_str(), mbg_program_version_str(), mbg_show_pzf_corr_info(), mbg_snprint_date_time(), mbg_snprint_hr_time(), mbg_snprint_hr_time_loc(), mbg_snprint_hr_tstamp(), mbg_snprint_revision(), mbg_str_date(), mbg_str_date_short(), mbg_str_dev_name(), mbg_str_pcps_hr_time_frac(), mbg_str_pcps_hr_time_offs(), mbg_str_pcps_hr_time_raw(), mbg_str_pcps_tstamp_raw(), mbg_str_pos_alt(), mbg_str_pos_dms(), mbg_str_time(), mbg_str_time_long(), mbg_str_time_short(), mbg_str_ucap(), nl_read(), pcps_port_str(), pcps_serial_str(), pcps_str_tm_gps_date_time(), setup_device_type_name(), show_ext_stat_info(), show_pout(), show_ucap_event(), sn_printf_timespec(), snprint_02u(), snprint_04u(), snprint_chk_time_info(), snprint_ctry_tm_long(), snprint_ctry_wday(), snprint_dev_name(), snprint_gmtime_error(), snprint_ip4_addr(), snprint_ip4_cidr_addr(), snprint_ip6_addr(), snprint_ip6_cidr_addr(), snprint_ip6_cidr_mask_addr(), snprint_nano_time(), snprint_nano_time_64(), snprint_octets(), snprint_time_t_to_iso(), snprint_utc_offs(), str_comp_data(), and swap_pos_doubles().

◆ strncpy_safe()

char* strncpy_safe	(	char *	dst,
		const char *	src,
		size_t	max_len
	)

A portable, safe implementation of strncpy()

In the original implementation of strncpy(), if the length of the string to be copied into the destination buffer exceeds the specified buffer length then the string in the output buffer is not 0-terminated.

Our implementation always forces a proper termination by 0, but unlike the original implementation of strncpy() it does not fill the whole remaining buffer space with '0' characters.

Parameters

[out]	dst	Pointer to the output buffer
[in]	src	Pointer to the input buffer
[in]	max_len	Size of the output buffer for 0-terminated string

Returns: Pointer to the destination buffer

See also: vsnprintf_safe; snprintf_safe; sn_cpy_str_safe; sn_cpy_char_safe

Definition at line 247 of file str_util.c.

References do_str_copy_safe().

Referenced by dev_open_finish_setup(), do_siocg_ioctl(), mbg_str_dev_name(), pcps_date_time_str(), pcps_tz_name_hr_status(), port_info_from_pcps_serial(), and setup_dev_fn_list().

◆ trim_leading_whitespace()

void trim_leading_whitespace ( char * s )

Trim whitespace at the beginning of a string.

Parameters

[in,out] s The string to be trimmed

Definition at line 353 of file str_util.c.

Referenced by trim_whitespace().

◆ trim_trailing_whitespace()

void trim_trailing_whitespace ( char * s )

Trim whitespace at the end of a string.

Parameters

[in,out] s The string to be trimmed

Definition at line 328 of file str_util.c.

Referenced by trim_whitespace().

◆ trim_whitespace()

void trim_whitespace ( char * s )

Trim both leading and trailing whitespace from a string.

Parameters

[in,out] s The string to be trimmed

Definition at line 387 of file str_util.c.

References trim_leading_whitespace(), and trim_trailing_whitespace().

Referenced by chk_sw_rev_name(), and mbgextio_setup_receiver_info().

◆ vsnprintf_safe()

int vsnprintf_safe	(	char *	s,
		size_t	max_len,
		const char *	fmt,
		va_list	args
	)

A portable, safe implementation of vsnprintf()

Unfortunately the behaviour of vsnprintf() and thus snprintf() differs in detail across various build environments and run time libraries.

If the output exceeds the buffer size and thus is truncated then:

Under Windows a negative value is returned and eventually no terminating 0 is written to the output buffer, so the output string may not be terminated properly.
Some versions of glibc return the number of bytes that would have been written to the buffer if the buffer would have been large enough, instead of the true number of characters that have been written to the buffer.

So subsequent calls like

n = snprintf( s, max_len, ... ); n += snprintf( &s[n], max_len - n, ... );

may always work properly, or fail with buffer overruns or stack corruption depending on the build environment. This wrapper function takes care that strings are always terminated properly, and that the returned value always matches the number of characters really written to the string buffer, excluding the terminating 0.

Note: The "size_t" type parameter used to specify the buffer size can be larger (e.g. "unsigned long") than the "int" type returned by mostly all functions of the printf() family. So if a very large buffer is specified, and a large number of characters (more than MAXINT) are written to that buffer then how can an "int" type return the large number of characters written to the buffer? We also try to workaround this here.

Parameters

[out]	s	The string buffer to be filled
[in]	max_len	Size of the output buffer for 0-terminated string
[in]	fmt	Format string according to subsequent parameters
[in]	args	Variable argument list in va_list format

Returns: Number of characters written to the output buffer, except the terminating 0

See also: snprintf_safe; strncpy_safe; sn_cpy_str_safe; sn_cpy_char_safe

Definition at line 121 of file str_util.c.

References mbg_buffer_specs_valid(), mbg_chk_snprint_results(), and mbg_vsnprintf.

Referenced by mbg_kdd_vsnprintf(), mbg_snprintf(), and snprintf_safe().

Variable Documentation

◆ str_not_avail

const char* str_not_avail

Referenced by mbg_str_pos(), pcps_date_time_str(), pcps_status_strs(), setup_asic_features(), and show_ptp_state().

Macros

Functions

Variables

Macro Definition Documentation

◆ _ext

◆ _sn_cpy_str_safe

Function Documentation

◆ mbg_buffer_specs_valid()

◆ mbg_chk_snprint_results()

◆ mbg_memcpy()

◆ mbg_memcpy_reversed()

◆ sn_cpy_char_safe()

◆ sn_cpy_str_safe()

◆ snprintf_safe()

◆ strncpy_safe()

◆ trim_leading_whitespace()

◆ trim_trailing_whitespace()

◆ trim_whitespace()

◆ vsnprintf_safe()

Variable Documentation

◆ str_not_avail