POSIX APIs

POSIX APIs Introduce

At present, the posix interface used by platform Armino only support the FreeRTOS V10.4, which is disabled by default

Use after opening macro definition CONFIG_FREERTOS_POSIX

Note

When using the posix function of FreeRTOS, you need to reference the FreeRTOS_POSIX.h header file before referencing the posix-related header files;
Related configurations can be customized in components/bk_rtos/freertos/posix/freertos_impl/include/portable/bk/FreeRTOS_POSIX_portable.h.

unistd APIs

#include <posix/unistd.h>

Defines the APIs related to system sleep

Header File

unistd.h

Functions

unsigned sleep(unsigned seconds)

Suspend execution for an interval of time.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/sleep.html

Note

Return value of a positive number is not yet supported.

Parameters: seconds – [in] The number of seconds to suspend execution.
Return values: 0 – - Upon successful completion.

int usleep(useconds_t usec)

Suspend execution for microsecond intervals.

This is a useful, non-POSIX function.

Parameters: usec – [in] The number of microseconds to suspend execution.
Return values: 0 – - Upon successful completion.

utils APIs

#include <posix/utils.h>

Define public interfaces

Header File

utils.h

Functions

size_t UTILS_strnlen(const char *const pcString, size_t xMaxLength)

Calculates the length of pcString, up to xMaxLength.

Parameters

pcString – [in] The string to find the length of.
xMaxLength – [in] The limit when searching for the end of pcString.

Returns

0 if pcString is NULL; otherwise, the length of pcString or xMaxLength, whichever is smaller.

int UTILS_AbsoluteTimespecToDeltaTicks(const struct timespec *const pxAbsoluteTime, const struct timespec *const pxCurrentTime, TickType_t *const pxResult)

Calculates the number of ticks between now and a given timespec.

Parameters

pxAbsoluteTime – [in] A time in the future, specified as seconds and nanoseconds since CLOCK_REALTIME’s 0.
pxCurrentTime – [in] current time, specified as seconds and nanoseconds.
pxResult – [out] Where the result of the conversion is stored. The result is rounded up for fractional ticks.

Returns

0 on success. Otherwise, ETIMEDOUT if pxAbsoluteTime is in the past, or EINVAL for invalid parameters.

int UTILS_TimespecToTicks(const struct timespec *const pxTimespec, TickType_t *const pxResult)

Converts a struct timespec to FreeRTOS ticks.

Parameters

pxTimespec – [in] The timespec to convert.
Where – [out] the result of the conversion is stored. The result is rounded up for fractional ticks.

Returns

0 on success. Otherwise, EINVAL for invalid parameters.

void UTILS_NanosecondsToTimespec(int64_t llSource, struct timespec *const pxDestination)

Converts an integer value to a timespec.

Parameters

llSource – [in] The value to convert.
pxDestination – [out] Where to store the converted value.

Returns

No return value.

int UTILS_TimespecAdd(const struct timespec *const x, const struct timespec *const y, struct timespec *const pxResult)

Calculates pxResult = x + y.

Parameters

x – [in] The first argument for addition.
y – [in] The second argument for addition.
pxResult – [out] Where the result of the calculation is stored.

Returns

-1 if any argument was NULL; 1 if result is negative (overflow); otherwise, 0.

int UTILS_TimespecAddNanoseconds(const struct timespec *const x, int64_t llNanoseconds, struct timespec *const pxResult)

Calculates pxResult = x + ( struct timespec ) nanosec.

Parameters

x – [in] The first argument for addition.
llNanoseconds – [in] The second argument for addition.
pxResult – [out] Where the result of the calculation is stored.

Returns

-1 if pxResult or x was NULL; 1 if result is negative; otherwise, 0.

int UTILS_TimespecSubtract(const struct timespec *const x, const struct timespec *const y, struct timespec *const pxResult)

Calculates pxResult = x - y. If the result is negative contents of pResult are undefined.

Parameters

x – [in] The first argument for subtraction.
y – [in] The second argument for subtraction.
pxResult – [out] Where the result of the calculation is stored.

Returns

-1 if any argument was NULL; 1 if result is negative; otherwise, 0.

int UTILS_TimespecCompare(const struct timespec *const x, const struct timespec *const y)

Compare x == y.

Parameters

x – [in] The first argument for comparison.
y – [in] The second argument for comparison.

Returns

0 if x == y; 1 if x > y; -1 if x < y or any argument was NULL

bool UTILS_ValidateTimespec(const struct timespec *const pxTimespec)

Checks that a timespec conforms to POSIX.

A valid timespec must have 0 <= tv_nsec < 1000000000.

Parameters: pxTimespec – [in] The timespec to validate.
Returns: true if the pxTimespec is valid, false otherwise.

errno APIs

Header files need to be include (#include <posix/errno.h>)

Define the meaning of the returned error value

Header File

errno.h

Macros

EPERM: Operation not permitted.

ENOENT: No such file or directory.

EBADF: Bad file descriptor.

EAGAIN: Resource unavailable, try again.

ENOMEM: Not enough space.

EEXIST: File exists.

EBUSY: Device or resource busy.

EINVAL: Invalid argument.

ENOSPC: No space left on device.

ERANGE: Result too large.

ENAMETOOLONG: File name too long.

EDEADLK: Resource deadlock would occur.

EOVERFLOW: Value too large to be stored in data type.

ENOSYS: Function not supported.

EMSGSIZE: Message too long.

ENOTSUP: Operation not supported.

ETIMEDOUT: Connection timed out.

fcntl APIs

#include <posix/fcntl.h>;

Defines the macro definition related to fcntl

Header File

fcntl.h

Macros

O_CLOEXEC: Close the file descriptor upon exec().

O_CREAT: Create file if it does not exist.

O_DIRECTORY: Fail if file is a non-directory file.

O_EXCL: Exclusive use flag.

O_NOCTTY: Do not assign controlling terminal.

O_NOFOLLOW: Do not follow symbolic links.

O_TRUNC: Truncate flag.

O_TTY_INIT: termios structure provides conforming behavior.

O_APPEND: Set append mode.

O_DSYNC: Write according to synchronized I/O data integrity completion.

O_NONBLOCK: Non-blocking mode.

O_RSYNC: Synchronized read I/O operations.

O_SYNC: Write according to synchronized I/O file integrity completion.

O_ACCMODE

O_EXEC: Open for execute only (non-directory files).

O_RDONLY: Open for reading only.

O_RDWR: Open for reading and writing.

O_SEARCH: Open directory for search only.

O_WRONLY: Open for writing only.

signal APIs

#include <posix/signal.h>;

Defines the signal related APIs

Header File

signal.h

Unions

union sigval

#include <signal.h>

Signal value.

Public Members

int sival_int: Integer signal value.

void *sival_ptr: Pointer signal value.

Structures

struct sigevent

Signal event structure.

Public Members

int sigev_notify: Notification type. A value of SIGEV_SIGNAL is not supported.

int sigev_signo: Signal number. This member is ignored.

union sigval sigev_value: Signal value. Only the sival_ptr member is used.

void (*sigev_notify_function)(union sigval): Notification function.

pthread_attr_t *sigev_notify_attributes: Notification attributes.

Macros

SIGEV_NONE: No asynchronous notification is delivered when the event of interest occurs.

SIGEV_SIGNAL: A queued signal, with an application-defined value, is generated when the event of interest occurs. Not supported.

SIGEV_THREAD: A notification function is called to perform notification.

mqueue APIs

#include <posix/mqueue.h>

Define interfaces related to system message queues

Header File

mqueue.h

Functions

int mq_close(mqd_t mqdes)

Close a message queue.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_close.html

@sideeffect Possible errno values

EBADF - The mqdes argument is not a valid message queue descriptor.

Return values

0 – - Upon successful completion
-1 – - A error occurred. errno is also set.

int mq_getattr(mqd_t mqdes, struct mq_attr *mqstat)

Get message queue attributes.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_getattr.html

@sideeffect Possible errno values

DBADF - The mqdes argument is not a valid message queue descriptor.

Return values

0 – - Upon successful completion
-1 – - A error occurred. errno is also set.

mqd_t mq_open(const char *name, int oflag, mode_t mode, struct mq_attr *attr)

Open a message queue.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_open.html

@sideeffect Possible errno values

EINVAL - name argument is invalid (not following name pattern), OR if O_CREAT is specified in oflag with attr argument not NULL and either mq_maxmsg or mq_msgsize is equal to or less than zero, OR either O_CREAT or O_EXCL is not set and a queue with the same name is unlinked but pending to be removed.

EEXIST - O_CREAT and O_EXCL are set and the named message queue already exists.

ENOSPC - There is insufficient space for the creation of the new message queue.

ENOENT - O_CREAT is not set and the named message queue does not exist.

Note

Supported name pattern: leading <slash> character in name is always required; the maximum length (excluding null-terminator) of the name argument can be NAME_MAX. The default value of NAME_MAX in FreeRTOS_POSIX_portable_default.h is 64, which can be overwritten by user.

Note

mode argument is not supported.

Note

Supported oflags: O_RDWR, O_CREAT, O_EXCL, and O_NONBLOCK.

Return values

Message – queue descriptor — Upon successful completion
(mqd_t) – - 1 — An error occurred. errno is also set.

ssize_t mq_receive(mqd_t mqdes, char *msg_ptr, size_t msg_len, unsigned int *msg_prio)

Receive a message from a message queue.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_receive.html

@sideeffect Possible errno values

EBADF - The mqdes argument is not a valid message queue descriptor open for reading.

EMSGSIZE - The specified message buffer size, msg_len, is less than the message size attribute of the message queue.

ETIMEDOUT - The O_NONBLOCK flag was not set when the message queue was opened, but no message arrived on the queue before the specified timeout expired.

EAGAIN - O_NONBLOCK was set in the message description associated with mqdes, and the specified message queue is empty.

Note

msg_prio argument is not supported. Messages are not checked for corruption.

Return values

The – length of the selected message in bytes - Upon successful completion. The message is removed from the queue
-1 – - An error occurred. errno is also set.

int mq_send(mqd_t mqdes, const char *msg_ptr, size_t msg_len, unsigned msg_prio)

Send a message to a message queue.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_send.html

@sideeffect Possible errno values

EBADF - The mqdes argument is not a valid message queue descriptor open for writing.

EMSGSIZE - The specified message length, msg_len, exceeds the message size attribute of the message queue, OR insufficient memory for the message to be sent.

ETIMEDOUT - The O_NONBLOCK flag was not set when the message queue was opened, but the timeout expired before the message could be added to the queue.

EAGAIN - The O_NONBLOCK flag is set in the message queue description associated with mqdes, and the specified message queue is full.

Note

msg_prio argument is not supported.

Return values

0 – - Upon successful completion.
-1 – - An error occurred. errno is also set.

ssize_t mq_timedreceive(mqd_t mqdes, char *msg_ptr, size_t msg_len, unsigned *msg_prio, const struct timespec *abstime)

Receive a message from a message queue with timeout.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_timedreceive.html

@sideeffect Possible errno values

EBADF - The mqdes argument is not a valid message queue descriptor open for reading.

EMSGSIZE - The specified message buffer size, msg_len, is less than the message size attribute of the message queue.

EINVAL - The process or thread would have blocked, and the abstime parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million.

ETIMEDOUT - The O_NONBLOCK flag was not set when the message queue was opened, but no message arrived on the queue before the specified timeout expired.

EAGAIN - O_NONBLOCK was set in the message description associated with mqdes, and the specified message queue is empty.

Note

msg_prio argument is not supported. Messages are not checked for corruption.

Return values

The – length of the selected message in bytes - Upon successful completion. The message is removed from the queue
-1 – - An error occurred. errno is also set.

int mq_timedsend(mqd_t mqdes, const char *msg_ptr, size_t msg_len, unsigned msg_prio, const struct timespec *abstime)

Send a message to a message queue with timeout.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_timedsend.html

@sideeffect Possible errno values

EBADF - The mqdes argument is not a valid message queue descriptor open for writing.

EMSGSIZE - The specified message length, msg_len, exceeds the message size attribute of the message queue, OR insufficient memory for the message to be sent.

EINVAL - The process or thread would have blocked, and the abstime parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million.

ETIMEDOUT - The O_NONBLOCK flag was not set when the message queue was opened, but the timeout expired before the message could be added to the queue.

EAGAIN - The O_NONBLOCK flag is set in the message queue description associated with mqdes, and the specified message queue is full.

Note

msg_prio argument is not supported.

Return values

0 – - Upon successful completion.
-1 – - An error occurred. errno is also set.

int mq_unlink(const char *name)

Remove a message queue.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/mq_unlink.html

@sideeffect Possible errno values

EINVAL - name argument is invalid. Refer to requirements on name argument in

mq_open()

.

ENOENT - The named message queue does not exist.

Return values

0 – - Upon successful completion.
-1 – - An error occurred. errno is also set.

Structures

struct mq_attr

Message queue attributes.

Public Members

long mq_flags: Message queue flags.

long mq_maxmsg: Maximum number of messages.

long mq_msgsize: Maximum message size.

long mq_curmsgs: Number of messages currently queued.

Type Definitions

typedef void *mqd_t: Message queue descriptor.

pthread APIs

#include <posix/pthread.h>;

APIs related to system tasks, including creation, destruction, etc

Header File

pthread.h

Functions

int pthread_attr_destroy(pthread_attr_t *attr)

Destroy the thread attributes object.

Return values: 0 – - Upon successful completion.

int pthread_attr_getdetachstate(const pthread_attr_t *attr, int *detachstate)

Get detachstate attribute.

Return values: 0 – - Upon successful completion.

int pthread_attr_getschedparam(const pthread_attr_t *attr, struct sched_param *param)

Get schedparam attribute.

Return values: 0 – - Upon successful completion.

int pthread_attr_getstacksize(const pthread_attr_t *attr, size_t *stacksize)

Get stacksize attribute.

Return values: 0 – - Upon successful completion.

int pthread_attr_init(pthread_attr_t *attr)

Initialize the thread attributes object.

Note

Currently, only stack size, sched_param, and detach state attributes are supported. Also see pthread_attr_get*() and pthread_attr_set*().

Return values: 0 – - Upon successful completion.

int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate)

Set detachstate attribute.

Return values

0 – - Upon successful completion
EINVAL – - The value of detachstate is not valid. Currently, supported detach states are — PTHREAD_CREATE_DETACHED and PTHREAD_CREATE_JOINABLE.

int pthread_attr_setschedparam(pthread_attr_t *attr, const struct sched_param *param)

Set schedparam attribute.

Return values

0 – - Upon successful completion.
EINVAL – - The value of param is not valid.
ENOTSUP – - An attempt was made to set the attribute to an unsupported value.

int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy)

Set the schedpolicy attribute.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_attr_setschedpolicy.html

Warning

This function is a stub and always returns 0.

Return values: 0 – - Upon successful completion.

int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stacksize)

Set stacksize attribute.

Return values

0 – - Upon successful completion.
EINVAL – - The value of stacksize is less than {PTHREAD_STACK_MIN}.

int pthread_barrier_destroy(pthread_barrier_t *barrier)

Destroy a barrier object.

Note

This function does not validate whether there is any thread blocking on the barrier before destroying.

Return values: 0 – - Upon successful completion.

int pthread_barrier_init(pthread_barrier_t *barrier, const pthread_barrierattr_t *attr, unsigned count)

Initialize a barrier object.

Note

attr is ignored.

Note

pthread_barrier_init() is implemented with FreeRTOS event group. To ensure count fits in event group, count may be at most 8 when configUSE_16_BIT_TICKS is 1; it may be at most 24 otherwise. configUSE_16_BIT_TICKS is configured in application FreeRTOSConfig.h file, which defines how many bits tick count type has. See further details and limitation about event group and configUSE_16_BIT_TICKS in FreeRTOS site.

Return values

0 – - Upon successful completion.
EINVAL – - The value specified by count is equal to zero.
ENOMEM – - count cannot fit into FreeRTOS event group type OR insufficient memory exists to initialize the barrier.

int pthread_barrier_wait(pthread_barrier_t *barrier)

Synchronize at a barrier.

Return values

PTHREAD_BARRIER_SERIAL_THREAD – - Upon successful completion, the first thread.
0 – - Upon successful completion, other thread(s).

int pthread_create(pthread_t *thread, const pthread_attr_t *attr, void *(*startroutine)(void*), void *arg)

Thread creation.

Return values

0 – - Upon successful completion.
EAGAIN – - Insufficient memory for either thread structure or task creation.

int pthread_cond_broadcast(pthread_cond_t *cond)

Broadcast a condition.

Return values: 0 – - Upon successful completion.

int pthread_cond_destroy(pthread_cond_t *cond)

Destroy condition variables.

Return values: 0 – - Upon successful completion.

int pthread_cond_init(pthread_cond_t *cond, const pthread_condattr_t *attr)

Initialize condition variables.

Note

attr is ignored and treated as NULL. Default setting is always used.

Return values

0 – - Upon successful completion.
ENOMEM – - Insufficient memory exists to initialize the condition variable.

int pthread_cond_signal(pthread_cond_t *cond)

Signal a condition.

Return values: 0 – - Upon successful completion.

int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex, const struct timespec *abstime)

Wait on a condition with a timeout.

Return values

0 – - Upon successful completion.
EINVAL – - The abstime argument passed in does not refer to an initialized structure OR the abstime parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million.
ETIMEDOUT – - The time specified by abstime to pthread_cond_timedwait() has passed.

int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex)

Wait on a condition.

Return values: 0 – - Upon successful completion.

int pthread_equal(pthread_t t1, pthread_t t2)

Compare thread IDs.

Return values

0 – - t1 and t2 are both not NULL && equal.
non-zero – - otherwise.

void pthread_exit(void *value_ptr)

Thread termination.

Return values: void – - this function cannot return to its caller.

int pthread_getschedparam(pthread_t thread, int *policy, struct sched_param *param)

Dynamic thread scheduling parameters access.

Note

policy is always set to SCHED_OTHER by this function.

Return values: 0 – - Upon successful completion.

int pthread_join(pthread_t thread, void **retval)

Wait for thread termination.

Return values

0 – - Upon successful completion.
EDEADLK – - The value specified by the thread argument to pthread_join() does not refer to a joinable thread OR multiple simultaneous calls to pthread_join() specifying the same target thread OR the value specified by the thread argument to pthread_join() refers to the calling thread.

int pthread_mutex_destroy(pthread_mutex_t *mutex)

Destroy a mutex.

Note

If there exists a thread holding this mutex, this function returns 0 with mutex not being destroyed.

Return values: 0 – - Upon successful completion.

int pthread_mutex_init(pthread_mutex_t *mutex, const pthread_mutexattr_t *attr)

Initialize a mutex.

Return values

0 – - Upon successful completion.
ENOMEM – - Insufficient memory exists to initialize the mutex structure.
EAGAIN – - Unable to initialize the mutex structure member(s).

int pthread_mutex_lock(pthread_mutex_t *mutex)

Lock a mutex.

Return values

0 – - Upon successful completion.
EINVAL – - the abstime parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million.
EDEADLK – - The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current thread already owns the mutex.

int pthread_mutex_timedlock(pthread_mutex_t *mutex, const struct timespec *abstime)

Lock a mutex with timeout.

Return values

0 – - Upon successful completion.
EINVAL – - The abstime argument passed in does not refer to an initialized structure OR the abstime parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million.
EDEADLK – - The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current thread already owns the mutex.
ETIMEDOUT – - The mutex could not be locked before the specified timeout expired.

int pthread_mutex_trylock(pthread_mutex_t *mutex)

Attempt to lock a mutex. Fail immediately if mutex is already locked.

Return values

0 – - Upon successful completion.
EINVAL – - the abstime parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million.
EDEADLK – - The mutex type is PTHREAD_MUTEX_ERRORCHECK and the current thread already owns the mutex.
EBUSY – - The mutex could not be acquired because it was already locked.

int pthread_mutex_unlock(pthread_mutex_t *mutex)

Unlock a mutex.

Return values

0 – - Upon successful completion.
EPERM – - The mutex type is PTHREAD_MUTEX_ERRORCHECK or PTHREAD_MUTEX_RECURSIVE, and the current thread does not own the mutex.

int pthread_mutexattr_destroy(pthread_mutexattr_t *attr)

Destroy the mutex attributes object.

Return values: 0 – - Upon successful completion.

int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *type)

Get the mutex type attribute.

Return values: 0 – - Upon successful completion.

int pthread_mutexattr_init(pthread_mutexattr_t *attr)

Initialize the mutex attributes object.

Note

Currently, only the type attribute is supported. Also see pthread_mutexattr_settype() and pthread_mutexattr_gettype().

Return values: 0 – - Upon successful completion.

int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type)

Set the mutex type attribute.

Return values

0 – - Upon successful completion.
EINVAL – - The value type is invalid.

pthread_t pthread_self(void)

Get the calling thread ID.

Return values: the – thread ID of the calling thread.

int pthread_setschedparam(pthread_t thread, int policy, const struct sched_param *param)

Dynamic thread scheduling parameters access.

Note

policy is ignored; only priority (param.sched_priority) may be changed.

Return values: 0 – - Upon successful completion.

Macros

PTHREAD_CREATE_DETACHED: Detached.

PTHREAD_CREATE_JOINABLE: Joinable (default).

PTHREAD_BARRIER_SERIAL_THREAD

PTHREAD_MUTEX_NORMAL: Non-robust, deadlock on relock, does not remember owner.

PTHREAD_MUTEX_ERRORCHECK: Non-robust, error on relock, remembers owner.

PTHREAD_MUTEX_RECURSIVE: Non-robust, recursive relock, remembers owner.

PTHREAD_MUTEX_DEFAULT: PTHREAD_MUTEX_NORMAL (default).

sched APIs

#include <posix/sched.h>;

APIs related to system scheduling

Header File

sched.h

Functions

int sched_get_priority_max(int policy)

Get priority limit (max).

http://pubs.opengroup.org/onlinepubs/9699919799/functions/sched_get_priority_max.html

Note

policy is ignored.

Returns

the maximum priority value (0-based) system configuration allows.

e.g. if configMAX_PRIORITIES == 7, this function returns (configMAX_PRIORITIES - 1). configMAX_PRIORITIES is configured in application FreeRTOSConfig.h file.

int sched_get_priority_min(int policy)

Get priority limit (min).

http://pubs.opengroup.org/onlinepubs/9699919799/functions/sched_get_priority_min.html

Note

policy is ignored.

int sched_yield(void)

Yield the processor.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/sched_yield.html

Return values: 0 – - Upon successful completion

Structures

struct sched_param

Scheduling parameters required for implementation of each supported scheduling policy.

Public Members

int sched_priority: Process or thread execution scheduling priority.

Macros

SCHED_OTHER: Another scheduling policy.

semaphore APIs

#include <posix/semaphore.h>;

Defines the APIs related to semaphores

Header File

semaphore.h

Functions

int sem_destroy(sem_t *sem)

Destroy an unnamed semaphore.

Note

Semaphore is destroyed regardless of whether there is any thread currently blocked on this semaphore.

Return values: 0 – - upon successful completion

int sem_getvalue(sem_t *sem, int *sval)

Get the value of a semaphore.

Note

If sem is locked, then the object to which sval points is set to zero.

Return values: 0 – - Upon successful completion

int sem_init(sem_t *sem, int pshared, unsigned value)

Initialize an unnamed semaphore.

@sideeffect Possible errno values

EINVAL - The value argument exceeds {SEM_VALUE_MAX}.

ENOSPC - A resource required to initialize the semaphore has been exhausted.

Note

pshared is ignored. Semaphores will always be considered “shared”.

Return values

0 – - upon successful completion
-1 – - otherwise. System error variable errno is also set in this case.

int sem_post(sem_t *sem)

Unlock a semaphore.

Return values: 0 – - upon successful completion

int sem_timedwait(sem_t *sem, const struct timespec *abstime)

Lock a semaphore with timeout.

@sideeffect Possible errno values

EINVAL - parameter specified a nanoseconds field value less than zero or greater than or equal to 1000 million

ETIMEDOUT - The semaphore could not be locked before the specified timeout expired.

Note

Deadlock detection is not implemented.

Return values

0 – - upon successful completion
-1 – - otherwise. System error variable errno is also set in this case.

int sem_trywait(sem_t *sem)

Lock a semaphore if available.

@sideeffect Possible errno values

EAGAIN - The semaphore was already locked, so it cannot be immediately locked by the

sem_trywait() operation.

Return values

0 – - upon successful completion
-1 – - otherwise. System error variable errno is also set in this case.

int sem_wait(sem_t *sem)

Lock a semaphore.

Note

Deadlock detection is not implemented.

Return values

0 – - upon successful completion
-1 – - otherwise. System error variable errno is also set in this case.

Type Definitions

typedef PosixSemType_t sem_t: Semaphore type.

time APIs

#include <posix/time.h>;

Defines APIs related to timers

Header File

time.h

Functions

clock_t clock(void)

Report CPU time used.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/clock.html

Note

This function does NOT report the number of ticks spent by the calling thread.

Returns: The number of FreeRTOS ticks since the scheduler was started minus the ticks spent in the idle task.

int clock_getcpuclockid(pid_t pid, clockid_t *clock_id)

Access a process CPU-time clock.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_getcpuclockid.html

Note

This function is currently unsupported.

Return values: EPERM –

int clock_getres(clockid_t clock_id, struct timespec *res)

Returns the resolution of a clock.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_getres.html

Note

clock_id is ignored

Note

This function stores the resolution of the FreeRTOS tick count in the object res points to.

Return values: 0 – - Upon successful execution

int clock_gettime(clockid_t clock_id, struct timespec *tp)

Returns the current value for the specified clock, clock_id.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_gettime.html

Note

clock_id is ignored

Note

this function does not check for overflows of time_t.

Return values: 0 – - Upon successful completion.

int clock_nanosleep(clockid_t clock_id, int flags, const struct timespec *rqtp, struct timespec *rmtp)

High resolution sleep with specifiable clock.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_nanosleep.html

Note

clock_id is ignored, as this function uses the FreeRTOS tick count as its clock.

Note

flags is ignored, if INCLUDE_vTaskDelayUntil is 0. i.e. the FreeRTOS function vTaskDelayUntil isn’t available.

Note

rmtp is also ignored, as signals are not implemented.

Return values

0 – - Upon successful completion.
EINVAL – - The rqtp argument specified a nanosecond value less than zero or greater than or equal to 1000 million.

int clock_settime(clockid_t clock_id, const struct timespec *tp)

Sets the time for the specified clock.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/clock_settime.html

Note

This function is currently unsupported, as FreeRTOS does not provide a function to modify the tick count.

Return values: -1 – with errno set to EPERM.

int nanosleep(const struct timespec *rqtp, struct timespec *rmtp)

High resolution sleep.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/nanosleep.html

Note

rmtp is ignored, as signals are not implemented.

Return values

0 – - Upon successful completion.
-1 – - The rqtp argument is invalid OR the rqtp argument specified a nanosecond value less than zero or greater than or equal to 1000 million.

int timer_create(clockid_t clockid, struct sigevent *evp, timer_t *timerid)

Create a per-process timer.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/timer_create.html

@sideeffect Possible errno values

ENOTSUP - If evp is NULL OR evp->sigen_notify == SIGEV_SIGNAL.

EAGAIN - The system lacks sufficient signal queuing resources to honor the request.

Note

clock_id is ignored, as this function used the FreeRTOS tick count as its clock.

Note

evp.sigev_notify must be set to SIGEV_THREAD, since signals are currently not supported.

Return values

0 – - Upon successful completion, with location referenced by timerid updated.
-1 – - If an error occurs. errno is also set.

int timer_delete(timer_t timerid)

Delete a per-process timer.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/timer_delete.html

Return values: 0 – - Upon successful completion.

int timer_getoverrun(timer_t timerid)

Get the timer overrun count.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/timer_getoverrun.html

Return values: 0 – - Always return 0, since signals are not supported.

int timer_gettime(timer_t timerid, struct itimerspec *value)

Get the amount of time until the timer expires.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/timer_gettime.html

Return values: 0 – - Upon successful completion.

int timer_settime(timer_t timerid, int flags, const struct itimerspec *value, struct itimerspec *ovalue)

Set the time until the next expiration of the timer.

http://pubs.opengroup.org/onlinepubs/9699919799/functions/timer_settime.html

@sideeffect Possible errno values

EINVAL - A value structure specified a nanosecond value less than zero or greater than or equal to 1000 million, AND the it_value member of that structure did not specify zero seconds and nanoseconds.

Return values

0 – - Upon successful completion.
-1 – - An error occurred, errno is also set.

Structures

struct timespec

represents an elapsed time

Public Members

time_t tv_sec: Seconds.

long tv_nsec: Nanoseconds.

struct itimerspec

timer

Public Members

struct timespec it_interval: Timer period.

struct timespec it_value: Timer expiration.

Macros

MICROSECONDS_PER_SECOND: Microseconds per second.

NANOSECONDS_PER_SECOND: Nanoseconds per second.

NANOSECONDS_PER_TICK: Nanoseconds per FreeRTOS tick.

CLOCK_REALTIME: The identifier of the system-wide clock measuring real time.

CLOCK_MONOTONIC: The identifier for the system-wide monotonic clock.

CLOCKS_PER_SEC

TIMER_ABSTIME