aboutsummaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorMattias Andrée <maandree@kth.se>2018-11-07 22:49:46 +0100
committerMattias Andrée <maandree@kth.se>2018-11-07 22:49:46 +0100
commitd16a6ab441f5a305a1c8a16d2811cb8d8594613d (patch)
tree872cdf84a776ac2e24fad2cd8c398859b91167c6 /README
parentMove section 3 man pages to man3/ and add libsimple.h.0 (diff)
downloadlibsimple-d16a6ab441f5a305a1c8a16d2811cb8d8594613d.tar.gz
libsimple-d16a6ab441f5a305a1c8a16d2811cb8d8594613d.tar.bz2
libsimple-d16a6ab441f5a305a1c8a16d2811cb8d8594613d.tar.xz
Update README
Signed-off-by: Mattias Andrée <maandree@kth.se>
Diffstat (limited to 'README')
-rw-r--r--README423
1 files changed, 2 insertions, 421 deletions
diff --git a/README b/README
index beea40a..19ba924 100644
--- a/README
+++ b/README
@@ -5,427 +5,8 @@ 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.
+name. However, some functions are seen as libsimple specific and do not
+have unnamespaced.
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.
-
- 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.
-
- 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, ...)