path: root/README

libsimple.h includes most POSIX header files so you do need to include lots of
headers in your code, and defines macros and functions that are useful for most
programs and libraries to simplify the code. It also provides *_MIN and *_MAX
values for integer data types.

All functions are namespaced with `libsimple_` and aliased with macro
definitions to unnamespaced names unless there already is a macro with that
name. However, the `libsimple_{,e,en}{,v}{mem,array}alloc` functions do
not have unnamespaced aliases as they are libsimple specific.

Programs using this library should define `char *argv0` and set it to
the 0:th command line argument.



CLOCK_MONOTONIC_RAW is defined to CLOCK_MONOTONIC unless CLOCK_MONOTONIC_RAW
already exists and unless DONT_DEFINE_CLOCK_MONOTONIC_RAW is defined.

AF_LOCAL, AF_UNIX, AF_FILE, PF_LOCAL, PF_UNIX, and PF_FILE are defined to
appropriate values provided that AF_LOCAL, AF_UNIX, or AF_FILE is already
defined.

The following macros are defined, unless already defined:

	MIN(A, B)
		Select the least of two values.

	MAX(A, B)
		Select the greatest of two values.

	MIN3(A, B, C)
		Select the least of three values.

	MAX3(A, B, C)
		Select the greatest of three values.

	ELEMSOF(ARR)
		Gets the number of elements in an array.

	STRLEN(STR)
		Gets the length of a string literal.

	INTSTRLEN(TYPE)
		Gets the maximum length any value with the integer type TYPE can
		have in base 10.

	TYPE_MAX(TYPE)
		Get the greatest value storable in an integer type.

	TYPE_MIN(TYPE)
		Get the least value storable in an integer type.

	FREE(PTR)
		(free(PTR), (PTR) = NULL, 0)
		Ensures that a pointer is not freed twiced.

	CLOSE(FD)
		((FD) >= 0 ? (close(FD), (FD) = -1, 0) : 0)
		Ensures that errno is not modified when closing an
		already closed file descriptor.

	Maximum values:
		BLKCNT64_MAX, BLKCNT_MAX, BLKSIZE_MAX, CC_MAX, CLOCKID_MAX,
		CLOCK_MAX, DEV_MAX, FSBLKCNT64_MAX, FSBLKCNT_MAX,
		FSFILCNT64_MAX, FSFILCNT_MAX, FSID_MAX, FSWORD_MAX, GID_MAX,
		ID_MAX, INO64_MAX, INO_MAX, KEY_MAX, LOFF_MAX, MODE_MAX,
		NLINK_MAX, OFF64_MAX, OFF_MAX, PID_MAX, QUAD_MAX, REGISTER_MAX,
		RLIM64_MAX, RLIM_MAX, SOCKLEN_MAX, SPEED_MAX, SUSECONDS_MAX,
		TCFLAG_MAX, TIMER_MAX, TIME_MAX, UID_MAX, USECONDS_MAX,
		U_QUAD_MAX

	Minimum values:
		BLKCNT64_MIN, BLKCNT_MIN, BLKSIZE_MIN, CC_MIN, CLOCKID_MIN,
		CLOCK_MIN, DEV_MIN, FSBLKCNT64_MIN, FSBLKCNT_MIN,
		FSFILCNT64_MIN, FSFILCNT_MIN, FSID_MIN, FSWORD_MIN, GID_MIN,
		ID_MIN, INO64_MIN, INO_MIN, KEY_MIN, LOFF_MIN, MODE_MIN,
		NLINK_MIN, OFF64_MIN, OFF_MIN, PID_MIN, QUAD_MIN, REGISTER_MIN,
		RLIM64_MIN, RLIM_MIN, SOCKLEN_MIN, SPEED_MIN, SUSECONDS_MIN,
		TCFLAG_MIN, TIMER_MIN, TIME_MIN, UID_MIN, USECONDS_MIN,
		U_QUAD_MIN

The following functions are defined (some as inline functions):

	int libsimple_close(int *)
		Ensures that errno is not modified when closing an
		already closed file descriptor.

	void *libsimple_rawmemchr(const void *, int)
		memchr without boundary check.

	void *libsimple_memrchr(const void *, int, size_t)
		Like memchr, except finds the last occurrence.

	void *libsimple_rawmemrchr(const void *, int, size_t)
		libsimple_memrchr without boundary check.

	char *libsimple_strchrnul(const char *, int)
		Like strchr, except returns the end if not found.

	char *libsimple_strend(const char *s)
		strchr(s, '\0')

	char *libsimple_inchrset(int c, const char *s)
		c && strchr(s, c)

	void *libsimple_memdup(const void *, size_t)
		Duplicate a memory segment.

	char *libsimple_strndup(const char *, size_t)
		Duplicate a substring.

	void *libsimple_mempcpy(void *, const void *, size_t)
		Like memcpy, except returns the byte after the
		last written byte.

	char *libsimple_strdupa(const char *)
		Like `strdup`, except the returned pointer is stack-allocated.
		This function is implemented as a macro and is only available
		when compiling with GCC or clang.

	char *libsimple_strndupa(const char *, size_t)
		Like `strndup`, except the returned pointer is stack-allocated.
		This function is implemented as a macro and is only available
		when compiling with GCC or clang.

	void *libsimple_memdupa(const void *, size_t)
		Like `memdup`, except the returned pointer is stack-allocated.
		This function is implemented as a macro and is only available
		when compiling with GCC or clang.

	int libsimple_isutf8(const char *s, int allow_modified_nul)
		Returns 1 if `s` is valid UTF-8 (Unicode codepoints are not
		validated) and 0 otherwise. If `allow_modified_nul` is non-zero,
		the byte sequence 0xC0 0x80 is allowed.

	int libsimple_asprintf(char **, const char *, ...)
		Like sprintf accept allocated the buffer.

	int libsimple_vasprintf(char **, const char *, va_list);
		Like vsprintf accept allocated the buffer.

	char *libsimple_asprintfa(const char *, ...)
		Like `asprintf` accept the the buffer is stack-allocated and
		returned instead of stored in a pointer. This function is
		implemented as a macro and is only available when compiling
		with GCC or clang.

	char *libsimple_vasprintfa(const char *, va_list)
		Like `vasprintf` accept the the buffer is stack-allocated and
		returned instead of stored in a pointer. This function is
		implemented as a macro and is only available when compiling
		with GCC or clang.

	void *libsimple_memmem(const void *s, size_t sn, const void *t, size_t tn)
		Finds the first occurrence of `t` in `s`.
		Length of `s` is `sn`. Length of `t` is `tn`.

	void *libsimple_memrmem(const void *s, size_t sn, const void *t, size_t tn)
		Finds the last occurrence of `t` in `s`.
		Length of `s` is `sn`. Length of `t` is `tn`.

	int libsimple_memstarts(const void *s, size_t sn, const void *t, size_t tn)
		Returns 1 if `s` starts with `t`, 0 otherwise.
		Length of `s` is `sn`. Length of `t` is `tn`.

	int libsimple_memends(const void *s, size_t sn, const void *t, size_t tn)
		Returns 1 if `s` ends with `t`, 0 otherwise.
		Length of `s` is `sn`. Length of `t` is `tn`.

	char *libsimple_strrstr(const char *s, const char *t)
		Finds the last occurrence of `t` in `s`.

	char *libsimple_strnstr(const char *s, const char *t, size_t n)
		Finds the first occurrence of the `n` first characters `t`
		in `n` first characters `s`.

	char *libsimple_strrnstr(const char *s, const char *t, size_t n)
		Finds the last occurrence of the `n` first characters `t`
		in `n` first characters `s`.

	int libsimple_strstarts(const char *s, const char *t)
		Returns 1 if `s` starts with `t`, 0 otherwise.

	int libsimple_strcasestarts(const char *, const char *)
		Like strstarts except case-insensitive.

	int libsimple_strends(const char *s, const char *t)
		Returns 1 if `s` ends with `t`, 0 otherwise.

	int libsimple_strcaseends(const char *, const char *)
		Like strends except case-insensitive.

	char *libsimple_strcasestr(const char *, const char *)
		Like strstr except case-insensitive.

	char *libsimple_strrcasestr(const char *, const char *)
		Like strrstr except case-insensitive.

	char *libsimple_strncasestr(const char *, const char *, size_t)
		Like strnstr except case-insensitive.

	char *libsimple_strrncasestr(const char *, const char *, size_t)
		Like strrnstr except case-insensitive.

	int libsimple_strcmpnul(const char *, const char *)
		Like strcmp excepts NULL and gives it a value less than
		the empty string

	int libsimple_strncmpnul(const char *, const char *, size_t)
		Like strncmp excepts NULL and gives it a value less than
		the empty string

	int libsimple_strcasecmpnul(const char *, const char *)
		Like strcasecmp excepts NULL and gives it a value less
		than the empty string

	int libsimple_strncasecmpnul(const char *, const char *, size_t)
		Like strncasecmp excepts NULL and gives it a value less
		than the empty string

	int libsimple_streq(const char *a, const char *b)
		!strcmp(a, b)

	int libsimple_strneq(const char *a, const char *b, size_t n)
		!strncmp(a, b, n)

	int libsimple_streqnul(const char *a, const char *b)
		!strcmpnul(a, b)

	int libsimple_strneqnul(const char *a, const char *b, size_t n)
		!strncmpnul(a, b, n)

	int libsimple_strcaseeq(const char *a, const char *b)
		!strcasecmp(a, b)

	int libsimple_strncaseeq(const char *a, const char *b, size_t n)
		!strncasecmp(a, b, n)

	int libsimple_strcaseeqnul(const char *a, const char *b)
		!strcasecmpnul(a, b)

	int libsimple_strncaseeqnul(const char *a, const char *b, size_t n)
		!strncasecmpnul(a, b, n)

	void *libsimple_vmalloczn(int, size_t, va_list)
		Like malloczn accept uses va_list instead of variadic arguments.

	void *libsimple_vmallocn(size_t, va_list)
		Like mallocn accept uses va_list instead of variadic arguments.

	void *libsimple_vcallocn(size_t, va_list)
		Like callocn accept uses va_list instead of variadic arguments.

	void *libsimple_vreallocn(void *, size_t, va_list)
		Like reallocn accept uses va_list instead of variadic arguments.

	void *libsimple_mallocz(int, size_t)
		Identical to malloc if first argument is zero,
		Identical to calloc, with 1 as the first argument, if first
		argument is non-zero.

	void *libsimple_malloczn(int, size_t, ... /*, (size_t)0 */)
		Identical to mallocn if first argument is zero,
		Identical to callocn if first argument is non-zero.

	void *libsimple_mallocn(size_t, ... /*, (size_t)0 */)
		Like malloc, accept uses the product of all argument, until
		the first 0-argument, the first argument must not be 0.

	void *libsimple_callocn(size_t, ... /*, (size_t)0 */)
		Like calloc, accept uses the product of all argument, until
		the first 0-argument, the first argument must not be 0.

	void *libsimple_reallocn(void *, size_t, ... /*, (size_t)0 */)
		Like realloc, accept uses the product of all argument,
		not counting the first argument, until the first 0-argument,
		the second argument must not be 0.

	char *libsimple_getenv_ne(const char *)
		Like getenv, except returns NULL if the value
		of the environment variable is the empty string.

	const char *libsimple_getenv_e(const char *)
		Like getenv, except returns the empty string if the
		value of the environment variable is undefined.

	int libsimple_vputenvf(const char *, va_list)
		Format a string and call putenv.

	int libsimple_putenvf(const char *, ...)
		Format a string and call putenv.

	void libsimple_vweprintf(const char *, va_list)
		Identical to libsimple_weprintf, except using va_list.

	void libsimple_weprintf(const char *fmt, ...)
		Similar to printf, except prints to stderr and:
		* unless `fmt` starts with "usage: " the `argv` follow by
		  ": " is prepended to the printed string,
		* if `fmt` ends with ":", " " followed by `strerror(errno)`
		  and "\n" and appended to the printed string, and
		* if `fmt` does not end with ":" or "\n", "\n" and appended to
		  the printed string.

		libsimple.h defines `extern int libsimple_default_failure_exit`.

	void libsimple_venprintf(int status, const char *, va_list)
		Like libsimple_vweprintf, but calls exit(status) afterwards.

	void libsimple_enprintf(int status, const char *, ...)
		Like libsimple_weprintf, but calls exit(status) afterwards.

	void libsimple_veprintf(const char *, va_list)
		Like libsimple_veprintf, but calls exit(libsimple_default_failure_exit)
		afterwards.

	void libsimple_eprintf(const char *, ...)
		Like libsimple_weprintf, but calls exit(libsimple_default_failure_exit)
		afterwards.

		libsimple.h defines `extern int libsimple_default_failure_exit`.

	int libsimple_sumtimespec(struct timespec *, const struct timespec *,
	  const struct timespec *)
		Returns the sum of two timestamps.

	int libsimple_difftimespec(struct timespec *, const struct timespec *,
	  const struct timespec *)
		Returns the difference of two timestamps.

	int libsimple_multimespec(struct timespec *, const struct timespec *, int)
		Multiplies a timestamp with an integer.

	int libsimple_cmptimespec(const struct timespec *, const struct timespec *)
		Compares two timestamps, same return semantics as strcmp.

	int libsimple_sumtimeval(struct timeval *, const struct timeval *,
	  const struct timeval *)
		Returns the sum of two timestamps.

	int libsimple_difftimeval(struct timeval *, const struct timeval *,
	  const struct timeval *)
		Returns the difference of two timestamps.

	int libsimple_multimeval(struct timeval *, const struct timeval *, int)
		Multiplies a timestamp with an integer.

	int libsimple_cmptimeval(const struct timeval *, const struct timeval *)
		Compares two timestamps, same return semantics as strcmp.

	void libsimple_timeval2timespec(struct timespec *restrict,
	  const struct timeval *restrict)
		Converts a struct timeval to a struct timespec.

	int libsimple_timespec2timeval(struct timeval *restrict,
	  const struct timespec *restrict)
		Converts a struct timespec to a struct timeval.

	int libsimple_strtotimespec(struct timespec *restrict,
	  const char *restrict, char **restrict)
		Converts a string to a struct timespec.

	int libsimple_strtotimeval(struct timeval *restrict,
	  const char *restrict, char **restrict)
		Converts a string to a struct timeval.

	char *libsimple_timespectostr(char *restrict,
	  const struct timespec *restrict)
		Converts a struct timespec to a string.

	char *libsimple_timevaltostr(char *restrict,
	  const struct timeval *restrict)
		Converts a struct timeval to a string.

	double libsimple_timespectodouble(const struct timespec *)
		Converts a struct timespec to a double.

	double libsimple_timevaltodouble(const struct timeval *)
		Converts a struct timeval to a double.

	void libsimple_doubletotimespec(struct timespec *, double)
		Converts a double to a struct timespec.

	void libsimple_doubletotimeval(struct timeval *, double)
		Converts a double to a struct timeval.

	char *libsimple_minimise_number_string(char *)
		Assumes that the input string is a normal floating-point
		number and removes redundant characters, such '+' sign,
		leading zeroes and trailing zeroes after decimal point.
		The input pointer is returned.

	void libsimple_unlist(void *list, size_t i, size_t *np, size_t width)
		Removes element `i` from the list `list`. `*np` shall be the
		number of elements in the list, it will be updated by the
		function. `width` shall be the byte-width of each element.

		The macro LIBSIMPLE_UNLIST(LIST, I, NP) (alias to UNLIST if no
		such macro already exists) is idential to libsimple_unlist
		except `width` is automatically.


The following functions, which call `eprintf` on failure, are also defined:

	void libsimple_evputenvf(const char *, va_list)
	void libsimple_eputenvf(const char *, ...)
	void *libsimple_emallocz(int, size_t)
	void *libsimple_emalloc(size_t)
	void *libsimple_ecalloc(size_t, size_t)
	void *libsimple_erealloc(void *, size_t)
	char *libsimple_estrdup(const char *)
	char *libsimple_estrndup(const char *, size_t)
	void *libsimple_ememdup(const void *, size_t)
	void *libsimple_evmallocn(size_t, va_list)
	void *libsimple_evcallocn(size_t, va_list)
	void *libsimple_evreallocn(void *, size_t, va_list)
	void *libsimple_evmalloczn(int, size_t, va_list)
	void *libsimple_emalloczn(int, size_t, ...)
	void *libsimple_emallocn(size_t, ...)
	void *libsimple_ecallocn(size_t, ...)
	void *libsimple_ereallocn(void *, size_t, ...)


The following functions, which call `enprintf` on failure, are also defined,
the first argument is used as the first argument for `enprintf`:

	void libsimple_envputenvf(int, const char *, va_list)
	void libsimple_enputenvf(int, const char *, ...)
	void *libsimple_enmallocz(int, size_t)
	void *libsimple_enmalloc(int, size_t)
	void *libsimple_encalloc(int, size_t, size_t)
	void *libsimple_enrealloc(int, void *, size_t)
	char *libsimple_enstrdup(int, const char *)
	char *libsimple_enstrndup(int, const char *, size_t)
	void *libsimple_enmemdup(int, const void *, size_t)
	void *libsimple_envmallocn(int, size_t, va_list)
	void *libsimple_envcallocn(int, size_t, va_list)
	void *libsimple_envreallocn(int, void *, size_t, va_list)
	void *libsimple_envmalloczn(int, int, size_t, va_list)
	void *libsimple_enmalloczn(int, int, size_t, ...)
	void *libsimple_enmallocn(int, size_t, ...)
	void *libsimple_encallocn(int, size_t, ...)
	void *libsimple_enreallocn(int, void *, size_t, ...)