nlib
Platform.h File Reference

C-based declaration of the basic API. More...

#include <stddef.h>
#include <stdio.h>
#include <stdarg.h>
#include <string.h>
#include <time.h>
#include "nn/nlib/Platform_unix.h"
#include <smmintrin.h>
#include <nmmintrin.h>
#include <errno.h>

Go to the source code of this file.

Classes

struct  nlib_mq_attr
 Structure to store the settings and current status of a message queue. More...
 

Macros

#define RSIZE_MAX   0x7FFFFFFFFFFFFFFFLL
 Defines a value somewhat smaller than the maximum value of size_t. More...
 
Attributes

A macro for handling differences in attributes in every compiler.

#define NLIB_WARN(exp)   ("WARNING: " exp)
 Outputs a warning. More...
 
#define NLIB_ASSUME(cond)   switch (0) case 0: default: if (cond) ; else __builtin_unreachable() /* NOLINT */
 Indicates that cond is true and provides tips for optimizing the compiler. More...
 

Typedefs

typedef int32_t nlib_long_compatible_t
 Defines an integer type that is compatible with long using typedef.
 
typedef uint32_t nlib_ulong_compatible_t
 Defines an integer type that is compatible with unsigned long using typedef.
 

Functions

Errors

Utilities related to error values.

const char * nlib_error_string (errno_t e)
 Returns a string literal corresponding to the error value of nlib. More...
 
unsigned int nlib_get_native_last_error (void)
 Returns the last generated native error code. More...
 
CRC-32, CRC-32C

Calculates quickly using dedicated instructions if SSE or NEON is available.

uint32_t nlib_crc32 (uint32_t crc32, const void *p, size_t n)
 This function calculates the CRC-32 checksum value for data. More...
 
uint32_t nlib_crc32c (uint32_t crc32c, const void *p, size_t n)
 This function calculates the CRC-32C checksum value for data. More...
 
Random Value Generation
NLIB_CHECK_RESULT errno_t nlib_gen_random (void *buf, size_t size)
 Generates a random value of size bytes and stores it in buf. More...
 
Allocation of Memory From the Operating System

Allows OS to allocate and free virtual memory spaces and to allocate and free physical memory.

errno_t nlib_mempagesize (size_t *size)
 Gets the page size. More...
 
errno_t nlib_virtual_alloc (void **ptr, size_t size)
 Allocates virtual memory address space. More...
 
errno_t nlib_virtual_free (void *ptr, size_t size)
 Frees the allocated virtual memory address space. More...
 
errno_t nlib_physical_alloc (void *ptr, size_t size, int prot)
 Allocates physical memory. More...
 
errno_t nlib_physical_free (void *ptr, size_t size)
 Frees the allocated physical memory. More...
 
errno_t nlib_mlock (void *addr, size_t len)
 The specified memory region is not swapped out. More...
 
errno_t nlib_munlock (void *addr, size_t len)
 The specified memory region can be swapped out. More...
 
Mutex

Provides an interface that is based on the pthread mutex.

errno_t nlib_mutex_init (nlib_mutex *mutex) NLIB_EXCLUDES(*mutex)
 Initializes a mutex. More...
 
errno_t nlib_mutex_recursive_init (nlib_mutex *mutex) NLIB_EXCLUDES(*mutex)
 Initializes a recursive mutex. More...
 
errno_t nlib_mutex_recursive_timed_init (nlib_mutex *mutex) NLIB_EXCLUDES(*mutex)
 Initializes a mutex that is recursive and can time out. More...
 
errno_t nlib_mutex_lock (nlib_mutex *mutex) NLIB_ACQUIRE(*mutex)
 Locks the specified mutex. More...
 
NLIB_CHECK_RESULT errno_t nlib_mutex_trylock (nlib_mutex *mutex) NLIB_TRY_ACQUIRE(0
 Locks mutex, but only if it is not locked. More...
 
NLIB_CHECK_RESULT errno_t nlib_mutex_trylock_for (nlib_mutex *mutex, nlib_duration delta) NLIB_TRY_ACQUIRE(0
 Locks the specified mutex. Times out. More...
 
errno_t nlib_mutex_unlock (nlib_mutex *mutex) NLIB_RELEASE(*mutex)
 Unlocks the specified mutex. More...
 
errno_t nlib_mutex_destroy (nlib_mutex *mutex) NLIB_EXCLUDES(*mutex)
 Destroys the specified mutex object and frees any associated resources. More...
 
static errno_t nlib_mutex_trylock_for_timespec (nlib_mutex *mutex, const struct timespec *tm) NLIB_TRY_ACQUIRE(0
 A version taking the timespec structure as the argument of nlib_mutex_trylock_for().
 
Semaphores
errno_t nlib_semaphore_init (nlib_semaphore *sem, int initial_count)
 Initializes the semaphore object specified by sem. More...
 
errno_t nlib_semaphore_wait (nlib_semaphore *sem)
 Waits until the semaphore count is no longer 0 and decrements the semaphore count by 1. More...
 
NLIB_CHECK_RESULT errno_t nlib_semaphore_trywait (nlib_semaphore *sem)
 Decrements the semaphore count by 1 if the count is not 0. More...
 
NLIB_CHECK_RESULT errno_t nlib_semaphore_trywait_for (nlib_semaphore *sem, nlib_duration duration)
 Decrements the semaphore count by 1 if the count is not 0. If 0, waits for the period specified by duration. More...
 
errno_t nlib_semaphore_post (nlib_semaphore *sem, int *previous_count)
 Increments the semaphore count by 1. More...
 
errno_t nlib_semaphore_post_ex (nlib_semaphore *sem, int release_count, int *previous_count)
 Increments the semaphore count by the amount specified by releaseCount. More...
 
errno_t nlib_semaphore_destroy (nlib_semaphore *sem)
 Destroys the semaphore count. More...
 
static errno_t nlib_semaphore_trywait_for_timespec (nlib_semaphore *sem, const struct timespec *tm)
 A version taking the timespec structure as the argument of nlib_semaphore_trywait_for().
 
Condition Variables

Provides an interface that is based on the pthread condition variables.

errno_t nlib_cond_init (nlib_cond *cond)
 Initializes a condition variable. More...
 
errno_t nlib_cond_signal (nlib_cond *cond)
 Resumes the execution of one thread that is waiting for condition variable cond. More...
 
errno_t nlib_cond_broadcast (nlib_cond *cond)
 Resumes the execution of all threads that are waiting for the conditional variable cond. More...
 
errno_t nlib_cond_wait (nlib_cond *cond, nlib_mutex *mutex) NLIB_REQUIRES(*mutex)
 Unlocks mutex and waits for a condition variable. It then relocks mutex after execution resumes. More...
 
NLIB_CHECK_RESULT errno_t nlib_cond_wait_for (nlib_cond *cond, nlib_mutex *mutex, nlib_duration duration) NLIB_REQUIRES(*mutex)
 Unlocks mutex and waits for just the duration amount of time for a condition variable. It then relocks mutex after execution resumes. More...
 
NLIB_CHECK_RESULT errno_t nlib_cond_wait_until (nlib_cond *cond, nlib_mutex *mutex, nlib_time abstime) NLIB_REQUIRES(*mutex)
 Unlocks mutex and waits until abstime for a condition variable. It then relocks mutex after execution resumes. More...
 
errno_t nlib_cond_destroy (nlib_cond *cond)
 Destroys a condition variable object. More...
 
static errno_t nlib_cond_wait_for_timespec (nlib_cond *cond, nlib_mutex *mutex, const struct timespec *tm) NLIB_REQUIRES(*mutex)
 A version taking the timespec structure as the argument of nlib_cond_wait_for().
 
static errno_t nlib_cond_wait_until_timespec (nlib_cond *cond, nlib_mutex *mutex, const struct timespec *tm) NLIB_REQUIRES(*mutex)
 A version taking the timespec structure as the argument of nlib_cond_wait_until().
 
Debugging and Debug Output
errno_t nlib_write_stdout (size_t *result, const void *buf, size_t count)
 Writes a string to standard output. More...
 
errno_t nlib_write_stderr (size_t *result, const void *buf, size_t count)
 Writes a string to standard error output. More...
 
void nlib_debug_break (void)
 A breakpoint. More...
 
errno_t nlib_debug_backtrace (size_t *result, void **buffer, size_t count)
 Stores backtraces in the array specified by buffer. More...
 
errno_t nlib_debug_backtrace_gettext (char *str, size_t strbufsize, void *const *buf, size_t count)
 Creates string information from the data obtained using the nlib_debug_backtrace function. More...
 
errno_t nlib_getenv (size_t *result, char *buf, size_t bufsize, const char *varname)
 Gets the value for the environment variable as a string. More...
 
Copying, comparing, and exploring a memory region.
static errno_t nlib_memcpy (void *s1, size_t s1max, const void *s2, size_t n)
 An implementation corresponding to N1078 memcpy_s. More...
 
static errno_t nlib_memmove (void *s1, size_t s1max, const void *s2, size_t n)
 An implementation corresponding to N1078 memmove_s. More...
 
static errno_t nlib_memset (void *buf, int ch, size_t n)
 Makes a function call corresponding to memset(buf, ch, n). More...
 
void * nlib_memccpy (void *dest, size_t dest_size, const void *src, size_t src_size, int c)
 Continues copying until c is found. Stops copying when it is found. More...
 
int nlib_memcmp (const void *buf1, const void *buf2, size_t n)
 Compares the n bytes from the starts of buf1 and buf2 as unsigned char data. More...
 
const void * nlib_memchr (const void *s, int c, size_t n)
 Searches the n bytes from the start of the memory region (s, s + n) and returns a pointer to byte c. More...
 
const void * nlib_memrchr (const void *s, int c, size_t n)
 Searches the n bytes from the end of memory region (s, s + n) and returns a pointer to byte c. More...
 
const void * nlib_memchr_not (const void *s, int c, size_t n)
 Searches the n bytes from the start of memory region(s, s + n) and returns a pointer that does not point to byte c. More...
 
const void * nlib_memchr_range_not (const void *s, const char *range, size_t n)
 Searches the n bytes from the start of memory region (s, s + n) and returns a pointer to a character not contained in range. More...
 
const void * nlib_memchr_lt (const void *s, int c, size_t n)
 Searches the n bytes from the start of memory region (s, s + n) and returns a pointer to data having a character less than byte c. More...
 
const void * nlib_memchr_gt (const void *s, int c, size_t n)
 Searches the n bytes from the start of memory region (s, s + n) and returns a pointer to data having a character larger than byte c. More...
 
const void * nlib_memchr_mb (const void *s, size_t n)
 Searches the n bytes from the start of memory region (s, s + n) and returns a pointer to the location where 0x80 or more bytes is stored. More...
 
size_t nlib_memspn (const void *buf, size_t len, const char *set, size_t n)
 Returns the length of the set of sub-bytes from the beginning of buf. The set of sub-bytes consists of only bytes contained in set. More...
 
size_t nlib_memcspn (const void *buf, size_t len, const char *set, size_t n)
 Returns the length of the set of sub-bytes from the beginning of buf. The set of sub-bytes consists of bytes other than those contained in set. More...
 
Function for null terminated strings.
const char * nlib_skipws (size_t *cnt_lf, const char **last_lf, const char *s, size_t n)
 Searches a string made up of n characters and returns the pointer to the first character found that is not a white-space character. More...
 
size_t nlib_strlen (const char *s)
 Internally calls strlen(). In some cases, it may operate as an independent implementation. More...
 
size_t nlib_strnlen (const char *s, size_t maxsize)
 An implementation corresponding to N1078 strnlen_s. More...
 
errno_t nlib_strcpy (char *s1, size_t s1max, const char *s2)
 An implementation corresponding to N1078 strcpy_s. More...
 
errno_t nlib_strncpy (char *s1, size_t s1max, const char *s2, size_t n)
 An implementation corresponding to N1078 strncpy_s. More...
 
const char * nlib_strchr (const char *s, int c)
 Searches for a character from the start of a string. More...
 
const char * nlib_strrchr (const char *s, int c)
 Searches for a character from the end of a string. More...
 
static const char * nlib_strchr_mb (const char *s)
 Searches for a character from the start of a string and then returns either the null character or the pointer to 0x80-0xFF bytes. More...
 
size_t nlib_wcslen (const wchar_t *s)
 Makes a call to thewcslen function. In some cases, it may operate as an independent implementation. More...
 
size_t nlib_wcsnlen (const wchar_t *s, size_t maxsize)
 An implementation corresponding to N1078 wcsnlen_s. More...
 
errno_t nlib_wcscpy (wchar_t *s1, size_t s1max, const wchar_t *s2)
 An implementation corresponding to N1078 wcscpy_s. More...
 
errno_t nlib_wcsncpy (wchar_t *s1, size_t s1max, const wchar_t *s2, size_t n)
 An implementation corresponding to N1078 wcsncpy_s. More...
 
Substitute for <tt>strtol()</tt>.

Substitutes for strtol(). For more information, see the item describing nlib_strto_int32().

errno_t nlib_strto_int32 (int32_t *result, const char *nptr, char **endptr, int base)
 Converts a string to the int32_t type. More...
 
errno_t nlib_strto_int64 (int64_t *result, const char *nptr, char **endptr, int base)
 Converts a string to the int64_t type. For details, see nlib_strto_int32().
 
errno_t nlib_strto_uint32 (uint32_t *result, const char *nptr, char **endptr, int base)
 Converts a string to the uint32_t type. For details, see nlib_strto_int32().
 
errno_t nlib_strto_uint64 (uint64_t *result, const char *nptr, char **endptr, int base)
 Converts a string to the uint64_t type. For details, see nlib_strto_int32().
 
errno_t nlib_strto_double (double *result, const char *nptr, char **endptr)
 Converts a string to the double type. For details, see nlib_strto_int32().
 
errno_t nlib_strto_float (float *result, const char *nptr, char **endptr)
 Converts a string to the float type. For details, see nlib_strto_int32().
 
errno_t nlib_strto_int32_fallback (int32_t *result, const char *nptr, char **endptr, int base)
 Converts a string to the int32_t type without using a standard C function. For details, see nlib_strto_int32().
 
errno_t nlib_strto_int64_fallback (int64_t *result, const char *nptr, char **endptr, int base)
 Converts a string to the int64_t type without using a standard C function. For details, see nlib_strto_int32().
 
errno_t nlib_strto_uint32_fallback (uint32_t *result, const char *nptr, char **endptr, int base)
 Converts a string to the uint32_t type without using a standard C function. For details, see nlib_strto_int32().
 
errno_t nlib_strto_uint64_fallback (uint64_t *result, const char *nptr, char **endptr, int base)
 Converts a string to the uint64_t type without using a standard C function. For details, see nlib_strto_int32().
 
errno_t nlib_strto_double_fallback (double *result, const char *nptr, char **endptr)
 Converts a string to the double type without using a standard C function. For details, see nlib_strto_int32().
 
errno_t nlib_strto_float_fallback (float *result, const char *nptr, char **endptr)
 Converts a string to the float type without using a standard C function. For details, see nlib_strto_int32().
 
static errno_t nlib_strto_int8 (int8_t *result, const char *nptr, char **endptr, int base)
 Converts a string to the int8_t type. For details, see nlib_strto_int32().
 
static errno_t nlib_strto_int16 (int16_t *result, const char *nptr, char **endptr, int base)
 Converts a string to the int16_t type. For details, see nlib_strto_int32().
 
static errno_t nlib_strto_uint8 (uint8_t *result, const char *nptr, char **endptr, int base)
 Converts a string to the int8_t type. For details, see nlib_strto_int32().
 
static errno_t nlib_strto_uint16 (uint16_t *result, const char *nptr, char **endptr, int base)
 Converts a string to the int16_t type. For details, see nlib_strto_int32().
 
Unicode

Unicode-related functionality is also implemented in the nn::nlib::unicode namespace.

errno_t nlib_wide_to_utf8 (size_t *utf8count, char *utf8, size_t buflen, const wchar_t *wcstr)
 Converts a UTF-16/UTF-32 string into a UTF-8 string. More...
 
errno_t nlib_utf8_to_wide (size_t *wccount, wchar_t *wcstr, size_t buflen, const char *utf8)
 Converts a UTF-8 string into a UTF-16/UTF-32 string. More...
 
errno_t nlib_memwide_to_utf8 (size_t *to_count, size_t *from_count, char *to, size_t to_size, const wchar_t *from, size_t from_size) NLIB_NONNULL_5
 Depending on the size of wchar_t, nlib_memutf16_to_utf8() or nlib_memutf32_to_utf8() is called.
 
errno_t nlib_memutf8_to_wide (size_t *to_count, size_t *from_count, wchar_t *to, size_t to_size, const char *from, size_t from_size) NLIB_NONNULL_5
 Depending on the size of wchar_t, nlib_memutf8_to_utf16 or nlib_memutf8_to_utf32 is called.
 
NLIB_CHECK_RESULT errno_t nlib_wcscplen (size_t *count, const wchar_t *str)
 Gets the number of code points in the string. More...
 
NLIB_CHECK_RESULT errno_t nlib_memcplen (size_t *codepoint_count, size_t *supplementary_codepoint_count, size_t *from_read, const char *from, size_t from_size)
 Gets the number of code points contained in the string and the number of supplementary characters contained in the string.. More...
 
errno_t nlib_swapendian_16 (uint16_t *p, size_t count)
 Swaps the endianness. More...
 
errno_t nlib_swapendian_32 (uint32_t *p, size_t count)
 Swaps the endianness. More...
 
errno_t nlib_swapendian_64 (uint64_t *p, size_t count)
 Swaps the endianness. More...
 
malloc
NLIB_CHECK_RESULT void * nlib_malloc (size_t size)
 A weak function that calls the C standard function malloc. nlib calls malloc via this function. More...
 
void nlib_free (void *ptr)
 A weak function that calls the C standard function free. nlib calls free via this function. More...
 
NLIB_CHECK_RESULT void * nlib_calloc (size_t nmemb, size_t size)
 A weak function that calls the C standard function calloc. nlib calls calloc via this function. More...
 
NLIB_CHECK_RESULT void * nlib_realloc (void *ptr, size_t size)
 A weak function that calls the C standard function realloc. nlib calls realloc via this function. More...
 
size_t nlib_malloc_size (const void *ptr)
 Returns the allocated memory size. More...
 
void nlib_free_size (void *ptr, size_t size)
 Frees memory of a specified size. The default action is to call the nlib_free function. More...
 
NLIB_CHECK_RESULT void * nlib_memalign (size_t alignment, size_t size)
 A weak function that calls the C standard function memalign. nlib calls memalign via this function. More...
 
Substitute for <tt>ctype.h<tt>.

A substitute for functions declared in ctype.h, a standard header for C. It isn't affected by the locale.

static int nlib_isalnum (int ch)
 If ch is an ASCII character '0'-'9', 'A'-'Z', or 'a'-'z', the function returns non-zero. Otherwise, the function returns 0.
 
static int nlib_isalpha (int ch)
 If ch is an ASCII character 'A'-'Z' or 'a'-'z', the function returns non-zero. Othewise, the function returns 0.
 
static int nlib_isblank (int ch)
 If ch is an ASCII character ' ' or '\t', the function returns non-zero. Otherwise, the function returns 0.
 
static int nlib_iscntrl (int ch)
 If ch is an ASCII code '0'-'31' or '127', the function returns non-zero. Otherwise, the function returns 0.
 
static int nlib_isdigit (int ch)
 If ch is an ASCII character '0'-'9', the function returns non-zero. Otherwise, the function returns 0.
 
static int nlib_isgraph (int ch)
 If ch is an ASCII character '33'-'126', the function returns non-zero. Otherwise, the function returns 0.
 
static int nlib_islower (int ch)
 If ch is an ASCII character 'a'-'z', the function returns non-zero. Otherwise, the function returns 0.
 
static int nlib_isprint (int ch)
 If ch is an ASCII character '32'-'126', the function returns non-zero. Otherwise, the function returns 0.
 
static int nlib_ispunct (int ch)
 If ch is an ASCII character '0'-'32' or '127', the function returns non-zero. Otherwise, the function returns 0.
 
static int nlib_isspace (int ch)
 If ch is an ASCII character ' ', '\t', or '\n', the function returns non-zero. Otherwise, the function returns 0.
 
static int nlib_isupper (int ch)
 If ch is an ASCII character 'A'-'Z', the function returns non-zero. Otherwise, the function returns 0.
 
static int nlib_isxdigit (int ch)
 If ch is an ASCII character '0'-'9', 'A'-'F', or 'a'-'f', the function returns non-zero. Otherwise, the function returns 0.
 
static int nlib_tolower (int ch)
 If ch is an ASCII character 'A'-'Z', the function returns its lowercase letter. Otherwise, the function returns ch.
 
static int nlib_toupper (int ch)
 If ch is an ASCII character 'a'-'z', the function returns its uppercase letter. Otherwise, the function returns ch.
 
count leading zeros, count trailing zeros, popcnt, bitreverse
static int nlib_popcnt16 (uint16_t x)
 Returns the number of bits that are 1. More...
 
static int nlib_popcnt32 (uint32_t x)
 Returns the number of bits that are 1. More...
 
static int nlib_popcnt64 (uint64_t x)
 Returns the number of bits that are 1. More...
 
static int nlib_clz32 (uint32_t x)
 Returns the number of consecutive zero bits, with respect to the most significant bit (MSB). More...
 
static int nlib_ctz32 (uint32_t x)
 Returns the number of consecutive zero bits, with respect to the least significant bit (LSB). More...
 
static int nlib_clz64 (uint64_t x)
 Returns the number of consecutive zero bits, with respect to the most significant bit (MSB). More...
 
static int nlib_ctz64 (uint64_t x)
 Returns the number of consecutive zero bits, with respect to the least significant bit (LSB). More...
 
static uint32_t nlib_bitreverse32 (uint32_t x)
 Reverses the bit order within an entire 32-bit integer. More...
 
static uint64_t nlib_bitreverse64 (uint64_t x)
 Reverses the bit order within an entire 64-bit integer. More...
 

Version

Macros and functions for getting the nlib version information.

#define NLIB_VERSION_YEAR   2016
 Defines an integer that corresponds to the year portion of the version number.
 
#define NLIB_VERSION_YEAR_SHORT   16
 Defines an integer that corresponds to the lower two digits of the year portion of the version number.
 
#define NLIB_VERSION_DATE   0920
 Defines an integer that corresponds to the month portion of the version number.
 
#define NLIB_VERSION   20160920
 Defines the version number. Defines numerical values that correspond to the year, month, and day of the release.
 
int nlib_getversion (void)
 Dynamically gets the nlib version. More...
 
int nlib_compiler_version (void)
 Dynamically obtains the compiler version used to compile nlib. More...
 

Time and Duration

Functions for getting times and durations, and sleeping based on times and durations.

typedef int64_t nlib_time
 The type expressing the time in increments of 100 ns from the zero starting point of 1970-01-01. A 64-bit signed integer.
 
typedef int64_t nlib_duration
 The type expressing the time in increments of 100 ns. A 64-bit signed integer.
 
errno_t nlib_epochtime (nlib_time *t)
 Gets the current time. More...
 
errno_t nlib_ticktime (nlib_duration *t)
 Gets the elapsed time since the system was last started. More...
 
errno_t nlib_sleep (nlib_duration t)
 Sleeps for the duration of t. More...
 
static errno_t nlib_epochtime_timespec (struct timespec *tm)
 A version taking the timespec structure as the argument of nlib_epochtime().
 
static errno_t nlib_ticktime_timespec (struct timespec *tm)
 A version taking the timespec structure as the argument of nlib_ticktime().
 
static errno_t nlib_sleep_timespec (const struct timespec *tm)
 A version taking the timespec structure as the argument of nlib_sleep().
 

TLS

Thread local storage (TLS) is a mechanism for accessing different memory for each thread.

typedef void(* nlib_tls_destructor) (void *tls_value)
 The type for the TLS destructor function called when the thread is ended. More...
 
NLIB_CHECK_RESULT errno_t nlib_tls_alloc (nlib_tls *tls, nlib_tls_destructor destr)
 Allocates a new ID for the specified TLS slot. More...
 
errno_t nlib_tls_free (nlib_tls tls)
 Frees the ID corresponding to the TLS slot. More...
 
errno_t nlib_tls_setvalue (nlib_tls tls, const void *value)
 Stores a value in a TLS slot. More...
 
errno_t nlib_tls_getvalue (nlib_tls tls, void **value)
 Gets the value from a TLS slot. More...
 

Spinlock

Performs spinlock. Spin lock can be statically initialized.

#define NLIB_SPINLOCK_INITIALIZER   (0)
 Macro for statically initializing nlib_spinlock.
 
typedef int32_t nlib_spinlock
 Spinlock variable type. Used by statically initializing with NLIB_SPINLOCK_INITIALIZER. More...
 
static void nlib_spinlock_init (nlib_spinlock *lock)
 Initializes the spinlock. More...
 
static void nlib_spinlock_lock (nlib_spinlock *lock)
 Locks the spinlock. Behavior is undefined if a recursive lock is performed. More...
 
static errno_t nlib_spinlock_trylock (nlib_spinlock *lock)
 Locks the spinlock. Returns 0 if successful or EBUSY if fails. More...
 
static void nlib_spinlock_unlock (nlib_spinlock *lock)
 Unlocks the spinlock. More...
 

Read-Write Locks

A mechanism for allowing multiple readers to access a read-write lock at the same time, and for allowing only exclusive access by the writer when updating.

#define NLIB_RWLOCK_INITIALIZER
 Constant for statically initializing nlib_rwlock.
 
typedef struct nlib_rwlock_ nlib_rwlock
 The type for a read-write lock object. More...
 
errno_t nlib_rwlock_init (nlib_rwlock *rwlock) NLIB_EXCLUDES(*rwlock)
 Initializes a read-write lock object. More...
 
errno_t nlib_rwlock_destroy (nlib_rwlock *rwlock) NLIB_EXCLUDES(*rwlock)
 Destroys a read-write lock object. More...
 
errno_t nlib_rwlock_rdlock (nlib_rwlock *rwlock) NLIB_ACQUIRE_SHARED(*rwlock)
 Gets the read lock, and enters the critical section. Blocks until it can get a lock. More...
 
errno_t nlib_rwlock_tryrdlock (nlib_rwlock *rwlock) NLIB_TRY_ACQUIRE_SHARED(0
 Gets the read lock, and attempts to enter the critical section. More...
 
errno_t nlib_rwlock_tryrdlock_for (nlib_rwlock *rwlock, nlib_duration duration) NLIB_TRY_ACQUIRE_SHARED(0
 Gets the read lock, and attempts to enter the critical section. Times out. More...
 
errno_t nlib_rwlock_tryrdlock_until (nlib_rwlock *rwlock, nlib_time abstime) NLIB_TRY_ACQUIRE_SHARED(0
 Gets the read lock, and attempts to enter the critical section. Times out. More...
 
errno_t nlib_rwlock_rdunlock (nlib_rwlock *rwlock) NLIB_RELEASE_SHARED(*rwlock)
 Releases the read lock. More...
 
errno_t nlib_rwlock_wrlock (nlib_rwlock *rwlock) NLIB_ACQUIRE(*rwlock)
 Gets a write lock, and enters the critical section. Blocks until it can get a lock. More...
 
errno_t nlib_rwlock_trywrlock (nlib_rwlock *rwlock) NLIB_TRY_ACQUIRE(0
 Gets a write lock, and attempts to enter the critical section. More...
 
errno_t nlib_rwlock_trywrlock_for (nlib_rwlock *rwlock, nlib_duration duration) NLIB_TRY_ACQUIRE(0
 Gets a write lock, and attempts to enter the critical section. Times out. More...
 
errno_t nlib_rwlock_trywrlock_until (nlib_rwlock *rwlock, nlib_time abstime) NLIB_TRY_ACQUIRE(0
 Gets a write lock, and attempts to enter the critical section. Times out. More...
 
errno_t nlib_rwlock_wrunlock (nlib_rwlock *rwlock) NLIB_RELEASE(*rwlock)
 Releases a write lock. More...
 
static errno_t nlib_rwlock_tryrdlock_for_timespec (nlib_rwlock *rwlock, const struct timespec *tm) NLIB_TRY_ACQUIRE_SHARED(0
 A version taking the timespec structure as the argument of nlib_rwlock_tryrdlock_for().
 
static errno_t nlib_rwlock_tryrdlock_until_timespec (nlib_rwlock *rwlock, const struct timespec *tm) NLIB_TRY_ACQUIRE_SHARED(0
 A version taking the timespec structure as the argument of nlib_rwlock_tryrdlock_until().
 
static errno_t nlib_rwlock_trywrlock_for_timespec (nlib_rwlock *rwlock, const struct timespec *tm) NLIB_TRY_ACQUIRE(0
 A version taking the timespec structure as the argument of nlib_rwlock_trywrlock_for().
 
static errno_t nlib_rwlock_trywrlock_until_timespec (nlib_rwlock *rwlock, const struct timespec *tm) NLIB_TRY_ACQUIRE(0
 A version taking the timespec structure as the argument of nlib_rwlock_trywrlock_until().
 

Conditional Variable for Read-Write Locks

A conditional variable available for nlib_rwlock.

#define NLIB_CONDRWLOCK_INITIALIZER   { NLIB_COND_INITIALIZER, NLIB_MUTEX_INITIALIZER }
 Constant for statically initializing nlib_condrwlock.
 
typedef struct nlib_condrwlock_ nlib_condrwlock
 Type of the conditional variable for read-write locks. More...
 
errno_t nlib_condrwlock_init (nlib_condrwlock *cond)
 Initializes a read-write lock conditional variable. More...
 
errno_t nlib_condrwlock_destroy (nlib_condrwlock *cond)
 Destroys a read-write lock conditional variable. More...
 
errno_t nlib_condrwlock_signal (nlib_condrwlock *cond)
 Resumes the execution of one thread that is waiting for the read-write lock conditional variable cond. More...
 
errno_t nlib_condrwlock_broadcast (nlib_condrwlock *cond)
 Resumes the execution of all threads that are waiting for the read-write lock conditional variable cond. More...
 
errno_t nlib_condrwlock_wait (nlib_condrwlock *cond, nlib_rwlock *rwlock, int rdlock)
 Unlocks rwlock and waits for a conditional variable. It then locks rwlock again after the execution resumes. More...
 
errno_t nlib_condrwlock_wait_for (nlib_condrwlock *cond, nlib_rwlock *rwlock, nlib_duration duration, int rdlock)
 Unlocks rwlock and waits for a conditional variable. It then locks rwlock again after the execution resumes. More...
 
errno_t nlib_condrwlock_wait_until (nlib_condrwlock *cond, nlib_rwlock *rwlock, nlib_time abstime, int rdlock)
 Unlocks rwlock and waits for a conditional variable. It then locks rwlock again after the execution resumes. More...
 
static errno_t nlib_condrwlock_wait_for_timespec (nlib_condrwlock *cond, nlib_rwlock *rwlock, const struct timespec *tm, int rdlock)
 A version taking the imespec structure as the argument of nlib_condrwlock_wait_for_timespec().
 
static errno_t nlib_condrwlock_wait_until_timespec (nlib_condrwlock *cond, nlib_rwlock *rwlock, const struct timespec *tm, int rdlock)
 A version taking the timespec structure as the argument of nlib_condrwlock_wait_until_timespec().
 

Barriers

Synchronizes multiple threads to the end of a particular task. Can be used repeatedly.

typedef struct nlib_barrier_ nlib_barrier
 The type for a barrier object. More...
 
errno_t nlib_barrier_init (nlib_barrier *barrier, unsigned int count)
 Initializes a barrier object. More...
 
errno_t nlib_barrier_destroy (nlib_barrier *barrier)
 Destroys a barrier object. More...
 
errno_t nlib_barrier_wait (nlib_barrier *barrier)
 Waits for a thread. More...
 

One-Time Execution

A mechanism for guaranteeing that a particular process is executed only once.

#define NLIB_ONCE_INIT   { 0 }
 The value for statically initializing nlib_onceflag.
 
typedef struct nlib_onceflag_ nlib_onceflag
 The structure to use with nlib_once.
 
typedef void(* nlib_oncefunc) (void)
 The type for functions to execute with nlib_once.
 
errno_t nlib_once (nlib_onceflag *flag, nlib_oncefunc func)
 Ensures that func is executed only one time at most. More...
 
errno_t nlib_tryonce (nlib_onceflag *flag, nlib_oncefunc func)
 Basically the same as nlib_once, but returns EBUSY if func is running on another thread. More...
 

Message Queue

See nlib_mq_open() for the features of nlib message queue.

typedef int32_t nlib_mq
 Handle associated with a message queue. If the handle is cleared to zero (using memset()), it will always be an invalid handle.
 
typedef void * nlib_mq_msg
 Type of messages stored in a message queue.
 
typedef void(* nlib_mq_msg_destructor) (nlib_mq_msg)
 Destructor function for messages taken from a message queue.
 
NLIB_CHECK_RESULT errno_t nlib_mq_open (nlib_mq *mq, const nlib_mq_attr *attr)
 Creates a message queue to be used to exchange messages across threads. More...
 
NLIB_CHECK_RESULT errno_t nlib_mq_getattr (nlib_mq mq, nlib_mq_attr *attr)
 Obtains the attribute set to the message queue indicated with a handle. More...
 
errno_t nlib_mq_close (nlib_mq mq)
 Closes the message queue indicated with a handle. More...
 
errno_t nlib_mq_readonly (nlib_mq mq)
 Sets the message queue indicated with a handle as receive-only. More...
 
NLIB_CHECK_RESULT errno_t nlib_mq_send (nlib_mq mq, nlib_mq_msg msg, int prio)
 Sends a message to a queue. More...
 
NLIB_CHECK_RESULT errno_t nlib_mq_send_until (nlib_mq mq, nlib_mq_msg msg, int prio, nlib_time abstime)
 Sends a messages with a time-out set to the queue. More...
 
NLIB_CHECK_RESULT errno_t nlib_mq_receive (nlib_mq mq, nlib_mq_msg *msg, int *prio)
 Receives a message from a queue. It is the user's responsibility to delete the received messages using a destructor function. More...
 
NLIB_CHECK_RESULT errno_t nlib_mq_receive_until (nlib_mq mq, nlib_mq_msg *msg, int *prio, nlib_time abstime)
 Receives a message with a time-out set from a queue. It is the user's responsibility to delete the received messages using a destructor function. More...
 
NLIB_CHECK_RESULT errno_t nlib_mq_drop (nlib_mq mq, nlib_mq_msg *msg, int *prio)
 Receives a message with the lowest priority from a queue. It is the user's responsibility to delete the received messages using a destructor function. More...
 

Threads

#define NLIB_THREAD_INVALID   (nlib_thread)(0)
 Value indicating an invalid thread.
 
typedef struct nlib_thread_attr_ nlib_thread_attr
 The thread attribute to apply to a newly created thread.
 
typedef void(* nlib_thread_func) (void *arg)
 A function to be run on a different thread. More...
 
typedef int nlib_thread_id
 A unique integer value for each thread.
 
errno_t nlib_yield (void)
 Relinquishes thread execution rights. More...
 
NLIB_CHECK_RESULT errno_t nlib_thread_create (nlib_thread *thread, const nlib_thread_attr *attr, nlib_thread_func func, void *arg)
 Creates and executes a new thread. More...
 
errno_t nlib_thread_join (nlib_thread thread)
 Waits for the thread to terminate. More...
 
errno_t nlib_thread_detach (nlib_thread thread)
 Detaches an executing thread. More...
 
errno_t nlib_thread_self (nlib_thread *thread)
 Stores the nlib_thread value corresponding to the executing thread. More...
 
errno_t nlib_thread_getconcurrency (unsigned int *num_cpu)
 Gets the number of hardware threads. More...
 
errno_t nlib_thread_getid (nlib_thread_id *id)
 Stores a unique integer value corresponding to the executing thread. More...
 
int nlib_thread_equal (nlib_thread th1, nlib_thread th2)
 Checks whether two threads point to the same thread. More...
 
errno_t nlib_thread_getcpu (int *result)
 Gets the CPU on which the called thread is executing. More...
 
errno_t nlib_thread_setaffinity (nlib_thread thread, uint32_t affinity)
 Sets a processor affinity mask for the specified thread. More...
 
errno_t nlib_thread_setname (nlib_thread thread, const char *name)
 Attaches a name to the thread. More...
 
errno_t nlib_thread_getname (nlib_thread thread, char *name, size_t len)
 Gets the thread name. More...
 
errno_t nlib_thread_attr_init (nlib_thread_attr *attr)
 Initializes a thread attribute object and sets it to the default. More...
 
errno_t nlib_thread_attr_setint (nlib_thread_attr *attr, int key, int value)
 Sets an integer corresponding to the key of the thread attribute object. More...
 
errno_t nlib_thread_attr_getint (const nlib_thread_attr *attr, int key, int *value)
 Gets the integer corresponding to the key of the thread attribute object. More...
 
errno_t nlib_thread_attr_setptr (nlib_thread_attr *attr, int key, void *value)
 Sets a pointer corresponding to the key of the thread attribute object. As of now, returns EINVAL only. More...
 
errno_t nlib_thread_attr_getptr (const nlib_thread_attr *attr, int key, void **value)
 Gets the pointer corresponding to the key of the thread attribute object. As of now, returns EINVAL only. More...
 
errno_t nlib_thread_attr_setstack (nlib_thread_attr *attr, void *stack_addr, size_t stack_size)
 Sets a stack setting for thread attribute objects.

Platform Implementation
Win32 nlib independent implementation (The set value is ignored)
Linux pthread_attr_getstack()
FreeBSD pthread_attr_getstack()
OS X pthread_attr_getstack()
CAFE nlib independent implementation
CTR nlib independent implementation
More...
 
errno_t nlib_thread_attr_getstack (const nlib_thread_attr *attr, void **stack_addr, size_t *stack_size)
 Obtains a stack setting for thread attribute objects. More...
 
errno_t nlib_thread_attr_destroy (nlib_thread_attr *attr)
 Destroys a thread-initialization object. More...
 
errno_t nlib_thread_getpriority (nlib_thread thread, int *priority)
 Gets the current execution priority of the thread. The meaning of the numerical value is implementation-dependent. More...
 
errno_t nlib_thread_setpriority (nlib_thread thread, int priority)
 Sets the execution priority of the thread. The meaning of the numerical value is implementation-dependent. More...
 
errno_t nlib_thread_priority_min (int *priority)
 Gets the smallest numerical value that can be specified for the execution priority. More...
 
errno_t nlib_thread_priority_max (int *priority)
 Gets the largest numerical value that can be specified for the execution priority. More...
 
errno_t nlib_thread_priority_default (int *priority)
 Gets the default numerical value that can be specified for the execution priority. More...
 
void nlib_thread_exit (void) NLIB_NORETURN
 Ends the called thread. More...
 
void nlib_thread_cleanup_push (void(*fn)(void *), void *arg)
 Pushes fn to a dedicated stack. More...
 
void nlib_thread_cleanup_pop (int exec)
 Deletes the handler at the top of the stack storing the cleanup handler. More...
 

Logging

Outputs logs to standard output, syslog, and files.

enum  nlib_log_priority { ,
  NLIB_LOG_VERBOSE,
  NLIB_LOG_DEBUG,
  NLIB_LOG_INFO,
  NLIB_LOG_WARN,
  NLIB_LOG_ERROR,
  NLIB_LOG_FATAL ,
  NLIB_LOG_LEVEL_EQUAL_OR_ABOVE = 0x10,
  NLIB_LOG_LEVEL_EQUAL_OR_BELOW = 0x20,
  NLIB_LOG_LEVEL_ALL = 0x30
}
 Defines the priority (level category) for output. More...
 
int nlib_log_print (int prio, const char *tag, const char *fmt,...)
 Outputs log messages. More...
 
int nlib_log_vprint (int prio, const char *tag, const char *fmt, va_list ap)
 Outputs log messages. More...
 
errno_t nlib_log_attr_setint (int prio, int key, int value)
 Specifies where to output the log for each level of priority. More...
 

Files

#define NLIB_FD_O_RDONLY   O_RDONLY
 Used for the flags parameter of the nlib_fd_open function.
 
#define NLIB_FD_O_WRONLY   O_WRONLY
 Used for the flags parameter of the nlib_fd_open function.
 
#define NLIB_FD_O_RDWR   O_RDWR
 Used for the flags parameter of the nlib_fd_open function.
 
#define NLIB_FD_O_APPEND   O_APPEND
 Used for the flags parameter of the nlib_fd_open function.
 
#define NLIB_FD_O_CREAT   O_CREAT
 Used for the flags parameter of the nlib_fd_open function.
 
#define NLIB_FD_O_TRUNC   O_TRUNC
 Used for the flags parameter of the nlib_fd_open function.
 
#define NLIB_FD_O_EXCL   O_EXCL
 Used for the flags parameter of the nlib_fd_open function.
 
#define NLIB_SEEK_SET   SEEK_SET
 Used for the whence parameter of the nlib_fd_seek function.
 
#define NLIB_SEEK_CUR   SEEK_CUR
 Used for the whence parameter of the nlib_fd_seek function.
 
#define NLIB_FD_INVALID   (-1)
 A macro defining invalid file descriptors.
 
typedef int64_t nlib_offset
 The offset to the file. A 64-bit integer.
 
typedef int nlib_fd
 The original file descriptor of nlib (a 32-bit integer value). More...
 
errno_t nlib_fd_open (nlib_fd *fd, const char *native_path, unsigned int flags, int mode)
 Opens a file. More...
 
static NLIB_CHECK_RESULT errno_t nlib_fd_creat (nlib_fd *fd, const char *native_path, int mode)
 Equivalent to nlib_fd_open(fd, native_path, NLIB_FD_O_CREAT | NLIB_FD_O_WRONLY | NLIB_FD_O_EXCL, mode). Note that it fails if the file already exists.
 
NLIB_CHECK_RESULT errno_t nlib_fd_close (nlib_fd fd)
 Closes a file. The file descriptor will be released even if an error is returned. More...
 
NLIB_CHECK_RESULT errno_t nlib_fd_read (size_t *result, nlib_fd fd, void *buf, size_t count)
 Reads (up to) count bytes from the file descriptor into buf. More...
 
NLIB_CHECK_RESULT errno_t nlib_fd_write (size_t *result, nlib_fd fd, const void *buf, size_t count)
 Writes (up to) count bytes from buf to the file descriptor. More...
 
NLIB_CHECK_RESULT errno_t nlib_fd_seek (nlib_offset *result, nlib_fd fd, nlib_offset offset, int whence)
 Changes the file offset. More...
 
NLIB_CHECK_RESULT errno_t nlib_fd_pread (size_t *result, nlib_fd fd, void *buf, size_t count, nlib_offset offset)
 Reads the file descriptor from the specified offset. The offset for the file descriptor will not be changed. More...
 
NLIB_CHECK_RESULT errno_t nlib_fd_pwrite (size_t *result, nlib_fd fd, const void *buf, size_t count, nlib_offset offset)
 Writes to the file descriptor at the specified offset. The offset for the file descriptor will not be changed. More...
 
NLIB_CHECK_RESULT errno_t nlib_fd_truncate (nlib_fd fd, nlib_offset length)
 Extends or truncates the file to be the specified size. More...
 
NLIB_CHECK_RESULT errno_t nlib_fd_getsize (nlib_offset *size, nlib_fd fd)
 Gets the file size. More...
 
NLIB_CHECK_RESULT errno_t nlib_fd_flush (nlib_fd fd)
 Flushes the write to the file descriptor. More...
 
errno_t nlib_fd_sync (nlib_fd fd)
 Synchronizes the content of a file in memory with what is on the device. More...
 
errno_t nlib_fd_native_handle (void **native_handle, nlib_fd fd)
 Gets (the equivalent of) the native file handle. More...
 
NLIB_CHECK_RESULT errno_t nlib_fd_readv (size_t *result, nlib_fd fd, const nlib_fd_iovec *iov, int iovcnt)
 Loads multiple non-continuous buffers from the file associated with fd. More...
 
NLIB_CHECK_RESULT errno_t nlib_fd_writev (size_t *result, nlib_fd fd, const nlib_fd_iovec *iov, int iovcnt)
 Writes from multiple non-continuous buffers to the file associated with fd. More...
 
NLIB_CHECK_RESULT errno_t nlib_fd_preadv (size_t *result, nlib_fd fd, const nlib_fd_iovec *iov, int iovcnt, nlib_offset offset)
 Same as the nlib_fd_readv function except when the pread or nlib_fd_pread function is used internally.
 
NLIB_CHECK_RESULT errno_t nlib_fd_pwritev (size_t *result, nlib_fd fd, const nlib_fd_iovec *iov, int iovcnt, nlib_offset offset)
 Same as the nlib_fd_writev function except when the pwrite or nlib_fd_pwrite function is used internally.
 
NLIB_CHECK_RESULT errno_t nlib_unlink (const char *native_path)
 Deletes a file. More...
 
NLIB_CHECK_RESULT errno_t nlib_mkdir (const char *native_path, unsigned int flags)
 Creates a directory. More...
 
NLIB_CHECK_RESULT errno_t nlib_rmdir (const char *native_path)
 Deletes a directory. More...
 
NLIB_CHECK_RESULT errno_t nlib_remove (const char *native_path)
 Deletes a file or directory. Calls nlib_unlink() for a file, or nlib_rmdir() for a directory.
 
NLIB_CHECK_RESULT errno_t nlib_rename (const char *old_path, const char *new_path)
 Renames a file. More...
 
NLIB_CHECK_RESULT errno_t nlib_dir_open (nlib_dir *dir, const char *native_path)
 Opens a directory. More...
 
errno_t nlib_dir_close (nlib_dir dir)
 Closes a directory. More...
 
NLIB_CHECK_RESULT errno_t nlib_dir_read (nlib_dirent *ent, nlib_dir dir)
 Reads one directory entry, if there are any. More...
 
errno_t nlib_is_dir (int *result, const char *native_path)
 Checks whether the path is for a directory. Sets 0 in *result and returns 0 if no path exists. More...
 
errno_t nlib_exist_path (int *result, const char *native_path)
 Checks whether the path exists. More...
 
errno_t nlib_disk_freespace (const char *native_path, uint64_t *free_bytes_available, uint64_t *total_bytes, uint64_t *total_free_bytes)
 Gets information related to the capacity of the storage region to which the specified path belongs. More...
 
const char * nlib_basename (const char *path)
 
const char * nlib_dirname (size_t *len, const char *path)
 

printf

Functions for handling differences with the standard library printf.

Description
When describing a format string for printf, you may need to pay attention to its portability. Please refer to the following information:
See also
https://google.github.io/styleguide/cppguide.html#64-bit_Portability
http://www.textdrop.net/google-styleguide-ja/cppguide.xml#64%E3%83%93%E3%83%83%E3%83%88%E3%81%AE%E7%A7%BB%E6%A4%8D%E6%80%A7
#define PRIdS   __PRIS_PREFIX "d"
 Used when a size_t type is shown by printf. Corresponds to %zd.
 
#define PRIxS   __PRIS_PREFIX "x"
 Used when a size_t type is shown by printf. Corresponds to %zx.
 
#define PRIuS   __PRIS_PREFIX "u"
 Used when a size_t type is shown by printf. Corresponds to %zu.
 
#define PRIXS   __PRIS_PREFIX "X"
 Used when a size_t type is shown by printf. Corresponds to %zX.
 
#define PRIoS   __PRIS_PREFIX "o"
 Used when a size_t type is shown by printf. Corresponds to %zo.
 
errno_t nlib_vsnprintf (size_t *count, char *buf, size_t size, const char *fmt, va_list args)
 A safer form of vsnprintf, with some differences from standard vsnprintf behavior. More...
 
errno_t nlib_snprintf (size_t *count, char *buf, size_t size, const char *fmt,...)
 A safer form of snprintf.
 
errno_t nlib_vdprintf (nlib_fd fd, size_t *count, const char *fmt, va_list args)
 The version of the vsnprintf function that outputs to a file descriptor.
 
errno_t nlib_dprintf (nlib_fd fd, size_t *count, const char *fmt,...)
 The version of the snprintf function that outputs to a file descriptor.
 
int nlib_printf (const char *fmt,...)
 The substitute for the printf function.
 
errno_t nlib_vsnwprintf (size_t *count, wchar_t *buf, size_t size, const wchar_t *fmt, va_list args)
 A safer form of vswprintf, with some differences from standard vswprintf behavior. More...
 
errno_t nlib_snwprintf (size_t *count, wchar_t *buf, size_t size, const wchar_t *fmt,...)
 A safer form of snwprintf.
 
errno_t nlib_vdwprintf (nlib_fd fd, size_t *count, const wchar_t *fmt, va_list args)
 The version of the vsnwprintf function that outputs to a file descriptor.
 
errno_t nlib_dwprintf (nlib_fd fd, size_t *count, const wchar_t *fmt,...)
 The version of the snwprintf function that outputs to a file descriptor.
 
int nlib_wprintf (const wchar_t *fmt,...)
 The substitute for the wprintf function.
 

Detailed Description

C-based declaration of the basic API.

Definition in file Platform.h.