Zephyr API Documentation  3.7.0
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
User mode and Syscall APIs

User mode and Syscall APIs. More...

Macros

#define K_OOPS(expr)
 Induce a kernel oops.
 
#define K_SYSCALL_VERIFY_MSG(expr, fmt, ...)
 Runtime expression check for system call arguments.
 
#define K_SYSCALL_VERIFY(expr)   K_SYSCALL_VERIFY_MSG(expr, #expr)
 Runtime expression check for system call arguments.
 
#define K_SYSCALL_MEMORY_SIZE_CHECK(ptr, size)    (((uintptr_t)(ptr) + (size)) >= (uintptr_t)(ptr))
 Macro to check if size is negative.
 
#define K_SYSCALL_MEMORY(ptr, size, write)
 Runtime check that a user thread has read and/or write permission to a memory area.
 
#define K_SYSCALL_MEMORY_READ(ptr, size)    K_SYSCALL_MEMORY(ptr, size, 0)
 Runtime check that a user thread has read permission to a memory area.
 
#define K_SYSCALL_MEMORY_WRITE(ptr, size)    K_SYSCALL_MEMORY(ptr, size, 1)
 Runtime check that a user thread has write permission to a memory area.
 
#define K_SYSCALL_MEMORY_ARRAY(ptr, nmemb, size, write)
 
#define K_SYSCALL_MEMORY_ARRAY_READ(ptr, nmemb, size)    K_SYSCALL_MEMORY_ARRAY(ptr, nmemb, size, 0)
 Validate user thread has read permission for sized array.
 
#define K_SYSCALL_MEMORY_ARRAY_WRITE(ptr, nmemb, size)    K_SYSCALL_MEMORY_ARRAY(ptr, nmemb, size, 1)
 Validate user thread has read/write permission for sized array.
 
#define K_SYSCALL_IS_OBJ(ptr, type, init)
 
#define K_SYSCALL_DRIVER_OP(ptr, api_name, op)
 Runtime check driver object pointer for presence of operation.
 
#define K_SYSCALL_SPECIFIC_DRIVER(_device, _dtype, _api)
 Runtime check that device object is of a specific driver type.
 
#define K_SYSCALL_OBJ(ptr, type)    K_SYSCALL_IS_OBJ(ptr, type, _OBJ_INIT_TRUE)
 Runtime check kernel object pointer for non-init functions.
 
#define K_SYSCALL_OBJ_INIT(ptr, type)    K_SYSCALL_IS_OBJ(ptr, type, _OBJ_INIT_ANY)
 Runtime check kernel object pointer for non-init functions.
 
#define K_SYSCALL_OBJ_NEVER_INIT(ptr, type)    K_SYSCALL_IS_OBJ(ptr, type, _OBJ_INIT_FALSE)
 Runtime check kernel object pointer for non-init functions.
 

Functions

static bool k_is_in_user_syscall (void)
 Return true if we are currently handling a system call from user mode.
 
int k_object_validate (struct k_object *ko, enum k_objects otype, enum _obj_init_check init)
 Ensure a system object is a valid object of the expected type.
 
void k_object_dump_error (int retval, const void *obj, struct k_object *ko, enum k_objects otype)
 Dump out error information on failed k_object_validate() call.
 
struct k_objectk_object_find (const void *obj)
 Kernel object validation function.
 
void k_object_wordlist_foreach (_wordlist_cb_func_t func, void *context)
 Iterate over all the kernel object metadata in the system.
 
void k_thread_perms_inherit (struct k_thread *parent, struct k_thread *child)
 Copy all kernel object permissions from the parent to the child.
 
void k_thread_perms_set (struct k_object *ko, struct k_thread *thread)
 Grant a thread permission to a kernel object.
 
void k_thread_perms_clear (struct k_object *ko, struct k_thread *thread)
 Revoke a thread's permission to a kernel object.
 
void k_thread_perms_all_clear (struct k_thread *thread)
 Revoke access to all objects for the provided thread.
 
void k_object_uninit (const void *obj)
 Clear initialization state of a kernel object.
 
void k_object_recycle (const void *obj)
 Initialize and reset permissions to only access by the caller.
 
static size_t k_usermode_string_nlen (const char *src, size_t maxlen, int *err)
 Obtain the size of a C string passed from user mode.
 
void * k_usermode_alloc_from_copy (const void *src, size_t size)
 Copy data from userspace into a resource pool allocation.
 
int k_usermode_from_copy (void *dst, const void *src, size_t size)
 Copy data from user mode.
 
int k_usermode_to_copy (void *dst, const void *src, size_t size)
 Copy data to user mode.
 
char * k_usermode_string_alloc_copy (const char *src, size_t maxlen)
 Copy a C string from userspace into a resource pool allocation.
 
int k_usermode_string_copy (char *dst, const char *src, size_t maxlen)
 Copy a C string from userspace into a provided buffer.
 
static int k_object_validation_check (struct k_object *ko, const void *obj, enum k_objects otype, enum _obj_init_check init)
 

Detailed Description

User mode and Syscall APIs.

Macro Definition Documentation

◆ K_OOPS

#define K_OOPS (   expr)

#include <zephyr/internal/syscall_handler.h>

Value:
do { \
if (expr) { \
arch_syscall_oops(_current->syscall_frame); \
} \
} while (false)

Induce a kernel oops.

This macro can be used to induce a kernel oops which will kill the calling thread.

Parameters
exprExpression to be evaluated
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_DRIVER_OP

#define K_SYSCALL_DRIVER_OP (   ptr,
  api_name,
  op 
)

#include <zephyr/internal/syscall_handler.h>

Value:
({ \
struct api_name *__device__ = (struct api_name *) \
((const struct device *)(ptr))->api; \
K_SYSCALL_VERIFY_MSG(__device__->op != NULL, \
"Operation %s not defined for driver " \
"instance %p", \
# op, __device__); \
})
Runtime device structure (in ROM) per driver instance.
Definition: device.h:403

Runtime check driver object pointer for presence of operation.

Validates if the driver object is capable of performing a certain operation.

Parameters
ptrUntrusted device instance object pointer
api_nameName of the driver API struct (e.g. gpio_driver_api)
opDriver operation (e.g. manage_callback)
Returns
0 on success, nonzero on failure
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_IS_OBJ

#define K_SYSCALL_IS_OBJ (   ptr,
  type,
  init 
)

#include <zephyr/internal/syscall_handler.h>

Value:
k_object_find((const void *)(ptr)), \
(const void *)(ptr), \
(type), (init)) == 0, "access denied")
struct k_object * k_object_find(const void *obj)
Kernel object validation function.
static int k_object_validation_check(struct k_object *ko, const void *obj, enum k_objects otype, enum _obj_init_check init)
Definition: syscall_handler.h:522
#define K_SYSCALL_VERIFY_MSG(expr, fmt,...)
Runtime expression check for system call arguments.
Definition: syscall_handler.h:372

◆ K_SYSCALL_MEMORY

#define K_SYSCALL_MEMORY (   ptr,
  size,
  write 
)

#include <zephyr/internal/syscall_handler.h>

Value:
&& !Z_DETECT_POINTER_OVERFLOW(ptr, size) \
&& (arch_buffer_validate((void *)(ptr), (size), (write)) \
== 0), \
"Memory region %p (size %zu) %s access denied", \
(void *)(ptr), (size_t)(size), \
(write) ? "write" : "read")
int arch_buffer_validate(const void *addr, size_t size, int write)
Check memory region permissions.
#define K_SYSCALL_MEMORY_SIZE_CHECK(ptr, size)
Macro to check if size is negative.
Definition: syscall_handler.h:410

Runtime check that a user thread has read and/or write permission to a memory area.

Checks that the particular memory area is readable and/or writeable by the currently running thread if the CPU was in user mode, and generates a kernel oops if it wasn't. Prevents userspace from getting the kernel to read and/or modify memory the thread does not have access to, or passing in garbage pointers that would crash/pagefault the kernel if dereferenced.

Parameters
ptrMemory area to examine
sizeSize of the memory area
writeIf the thread should be able to write to this memory, not just read it
Returns
0 on success, nonzero on failure
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_MEMORY_ARRAY

#define K_SYSCALL_MEMORY_ARRAY (   ptr,
  nmemb,
  size,
  write 
)

#include <zephyr/internal/syscall_handler.h>

Value:
({ \
size_t product; \
K_SYSCALL_VERIFY_MSG(!size_mul_overflow((size_t)(nmemb), \
(size_t)(size), \
&product), \
"%zux%zu array is too large", \
(size_t)(nmemb), (size_t)(size)) || \
K_SYSCALL_MEMORY(ptr, product, write); \
})
static bool size_mul_overflow(size_t a, size_t b, size_t *result)
Multiply two size_t integers.

◆ K_SYSCALL_MEMORY_ARRAY_READ

#define K_SYSCALL_MEMORY_ARRAY_READ (   ptr,
  nmemb,
  size 
)     K_SYSCALL_MEMORY_ARRAY(ptr, nmemb, size, 0)

#include <zephyr/internal/syscall_handler.h>

Validate user thread has read permission for sized array.

Used when the memory region is expressed in terms of number of elements and each element size, handles any overflow issues with computing the total array bounds. Otherwise see _SYSCALL_MEMORY_READ.

Parameters
ptrMemory area to examine
nmembNumber of elements in the array
sizeSize of each array element
Returns
0 on success, nonzero on failure
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_MEMORY_ARRAY_WRITE

#define K_SYSCALL_MEMORY_ARRAY_WRITE (   ptr,
  nmemb,
  size 
)     K_SYSCALL_MEMORY_ARRAY(ptr, nmemb, size, 1)

#include <zephyr/internal/syscall_handler.h>

Validate user thread has read/write permission for sized array.

Used when the memory region is expressed in terms of number of elements and each element size, handles any overflow issues with computing the total array bounds. Otherwise see _SYSCALL_MEMORY_WRITE.

Parameters
ptrMemory area to examine
nmembNumber of elements in the array
sizeSize of each array element
Returns
0 on success, nonzero on failure
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_MEMORY_READ

#define K_SYSCALL_MEMORY_READ (   ptr,
  size 
)     K_SYSCALL_MEMORY(ptr, size, 0)

#include <zephyr/internal/syscall_handler.h>

Runtime check that a user thread has read permission to a memory area.

Checks that the particular memory area is readable by the currently running thread if the CPU was in user mode, and generates a kernel oops if it wasn't. Prevents userspace from getting the kernel to read memory the thread does not have access to, or passing in garbage pointers that would crash/pagefault the kernel if dereferenced.

Parameters
ptrMemory area to examine
sizeSize of the memory area
Returns
0 on success, nonzero on failure
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_MEMORY_SIZE_CHECK

#define K_SYSCALL_MEMORY_SIZE_CHECK (   ptr,
  size 
)     (((uintptr_t)(ptr) + (size)) >= (uintptr_t)(ptr))

#include <zephyr/internal/syscall_handler.h>

Macro to check if size is negative.

K_SYSCALL_MEMORY can be called with signed/unsigned types and because of that if we check if size is greater or equal to zero, many static analyzers complain about no effect expression.

Parameters
ptrMemory area to examine
sizeSize of the memory area
Returns
true if size is valid, false otherwise
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_MEMORY_WRITE

#define K_SYSCALL_MEMORY_WRITE (   ptr,
  size 
)     K_SYSCALL_MEMORY(ptr, size, 1)

#include <zephyr/internal/syscall_handler.h>

Runtime check that a user thread has write permission to a memory area.

Checks that the particular memory area is readable and writable by the currently running thread if the CPU was in user mode, and generates a kernel oops if it wasn't. Prevents userspace from getting the kernel to read or modify memory the thread does not have access to, or passing in garbage pointers that would crash/pagefault the kernel if dereferenced.

Parameters
ptrMemory area to examine
sizeSize of the memory area
Returns
0 on success, nonzero on failure
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_OBJ

#define K_SYSCALL_OBJ (   ptr,
  type 
)     K_SYSCALL_IS_OBJ(ptr, type, _OBJ_INIT_TRUE)

#include <zephyr/internal/syscall_handler.h>

Runtime check kernel object pointer for non-init functions.

Calls k_object_validate and triggers a kernel oops if the check fails. For use in system call handlers which are not init functions; a fatal error will occur if the object is not initialized.

Parameters
ptrUntrusted kernel object pointer
typeExpected kernel object type
Returns
0 on success, nonzero on failure
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_OBJ_INIT

#define K_SYSCALL_OBJ_INIT (   ptr,
  type 
)     K_SYSCALL_IS_OBJ(ptr, type, _OBJ_INIT_ANY)

#include <zephyr/internal/syscall_handler.h>

Runtime check kernel object pointer for non-init functions.

See description of _SYSCALL_IS_OBJ. No initialization checks are done. Intended for init functions where objects may be re-initialized at will.

Parameters
ptrUntrusted kernel object pointer
typeExpected kernel object type
Returns
0 on success, nonzero on failure
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_OBJ_NEVER_INIT

#define K_SYSCALL_OBJ_NEVER_INIT (   ptr,
  type 
)     K_SYSCALL_IS_OBJ(ptr, type, _OBJ_INIT_FALSE)

#include <zephyr/internal/syscall_handler.h>

Runtime check kernel object pointer for non-init functions.

See description of _SYSCALL_IS_OBJ. Triggers a fatal error if the object is initialized. Intended for init functions where objects, once initialized, can only be re-used when their initialization state expires due to some other mechanism.

Parameters
ptrUntrusted kernel object pointer
typeExpected kernel object type
Returns
0 on success, nonzero on failure
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_SPECIFIC_DRIVER

#define K_SYSCALL_SPECIFIC_DRIVER (   _device,
  _dtype,
  _api 
)

#include <zephyr/internal/syscall_handler.h>

Value:
({ \
const struct device *_dev = (const struct device *)_device; \
K_SYSCALL_OBJ(_dev, _dtype) || \
K_SYSCALL_VERIFY_MSG(_dev->api == _api, \
"API structure mismatch"); \
})
const void * api
Address of the API structure exposed by the device instance.
Definition: device.h:409

Runtime check that device object is of a specific driver type.

Checks that the driver object passed in is initialized, the caller has correct permissions, and that it belongs to the specified driver subsystems. Additionally, all devices store a structure pointer of the driver's API. If this doesn't match the value provided, the check will fail.

This provides an easy way to determine if a device object not only belongs to a particular subsystem, but is of a specific device driver implementation. Useful for defining out-of-subsystem system calls which are implemented for only one driver.

Parameters
_deviceUntrusted device pointer
_dtypeExpected kernel object type for the provided device pointer
_apiExpected driver API structure memory address
Returns
0 on success, nonzero on failure
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_VERIFY

#define K_SYSCALL_VERIFY (   expr)    K_SYSCALL_VERIFY_MSG(expr, #expr)

#include <zephyr/internal/syscall_handler.h>

Runtime expression check for system call arguments.

Used in handler functions to perform various runtime checks on arguments, and generate a kernel oops if anything is not expected.

Parameters
exprBoolean expression to verify, a false result will trigger an oops. A stringified version of this expression will be printed.
Returns
0 on success, nonzero on failure
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ K_SYSCALL_VERIFY_MSG

#define K_SYSCALL_VERIFY_MSG (   expr,
  fmt,
  ... 
)

#include <zephyr/internal/syscall_handler.h>

Value:
({ \
bool expr_copy = !(expr); \
if (expr_copy) { \
TOOLCHAIN_IGNORE_WSHADOW_BEGIN \
LOG_MODULE_DECLARE(os, CONFIG_KERNEL_LOG_LEVEL); \
TOOLCHAIN_IGNORE_WSHADOW_END \
LOG_ERR("syscall %s failed check: " fmt, \
__func__, ##__VA_ARGS__); \
} \
expr_copy; })

Runtime expression check for system call arguments.

Used in handler functions to perform various runtime checks on arguments, and generate a kernel oops if anything is not expected, printing a custom message.

Parameters
exprBoolean expression to verify, a false result will trigger an oops
fmtPrintf-style format string (followed by appropriate variadic arguments) to print on verification failure
Returns
False on success, True on failure
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

Function Documentation

◆ k_is_in_user_syscall()

static bool k_is_in_user_syscall ( void  )
inlinestatic

#include <zephyr/internal/syscall_handler.h>

Return true if we are currently handling a system call from user mode.

Inside z_vrfy functions, we always know that we are handling a system call invoked from user context.

However, some checks that are only relevant to user mode must instead be placed deeper within the implementation. This API is useful to conditionally make these checks.

For performance reasons, whenever possible, checks should be placed in the relevant z_vrfy function since these are completely skipped when a syscall is invoked.

This will return true only if we are handling a syscall for a user thread. If the system call was invoked from supervisor mode, or we are not handling a system call, this will return false.

Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.
Returns
whether the current context is handling a syscall for a user mode thread

◆ k_object_dump_error()

void k_object_dump_error ( int  retval,
const void *  obj,
struct k_object ko,
enum k_objects  otype 
)

#include <zephyr/internal/syscall_handler.h>

Dump out error information on failed k_object_validate() call.

Parameters
retvalReturn value from k_object_validate()
objKernel object we were trying to verify
koIf retval=-EPERM, struct k_object * that was looked up, or NULL
otypeExpected type of the kernel object
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_object_find()

struct k_object * k_object_find ( const void *  obj)

#include <zephyr/internal/syscall_handler.h>

Kernel object validation function.

Retrieve metadata for a kernel object. This function is implemented in the gperf script footer, see gen_kobject_list.py

Parameters
objAddress of kernel object to get metadata
Returns
Kernel object's metadata, or NULL if the parameter wasn't the memory address of a kernel object
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_object_recycle()

void k_object_recycle ( const void *  obj)

#include <zephyr/internal/syscall_handler.h>

Initialize and reset permissions to only access by the caller.

Intended for scenarios where objects are fetched from slab pools and may have had different permissions set during prior usage.

This is only intended for pools of objects, where such objects are acquired and released to the pool. If an object has already been used, we do not want stale permission information hanging around, the object should only have permissions on the caller. Objects which are not managed by a pool-like mechanism should not use this API.

The object will be marked as initialized and the calling thread granted access to it.

Parameters
objAddress of the kernel object
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_object_uninit()

void k_object_uninit ( const void *  obj)

#include <zephyr/internal/syscall_handler.h>

Clear initialization state of a kernel object.

Intended for thread objects upon thread exit, or for other kernel objects that were released back to an object pool.

Parameters
objAddress of the kernel object
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_object_validate()

int k_object_validate ( struct k_object ko,
enum k_objects  otype,
enum _obj_init_check  init 
)

#include <zephyr/internal/syscall_handler.h>

Ensure a system object is a valid object of the expected type.

Searches for the object and ensures that it is indeed an object of the expected type, that the caller has the right permissions on it, and that the object has been initialized.

This function is intended to be called on the kernel-side system call handlers to validate kernel object pointers passed in from userspace.

Parameters
koKernel object metadata pointer, or NULL
otypeExpected type of the kernel object, or K_OBJ_ANY if type doesn't matter
initIndicate whether the object needs to already be in initialized or uninitialized state, or that we don't care
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.
Returns
0 If the object is valid -EBADF if not a valid object of the specified type -EPERM If the caller does not have permissions -EINVAL Object is not initialized

◆ k_object_validation_check()

static int k_object_validation_check ( struct k_object ko,
const void *  obj,
enum k_objects  otype,
enum _obj_init_check  init 
)
inlinestatic

◆ k_object_wordlist_foreach()

void k_object_wordlist_foreach ( _wordlist_cb_func_t  func,
void *  context 
)

#include <zephyr/internal/syscall_handler.h>

Iterate over all the kernel object metadata in the system.

Parameters
funcfunction to run on each struct k_object
contextContext pointer to pass to each invocation
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_thread_perms_all_clear()

void k_thread_perms_all_clear ( struct k_thread thread)

#include <zephyr/internal/syscall_handler.h>

Revoke access to all objects for the provided thread.

Note
Unlike k_thread_perms_clear(), this function will not clear permissions on public objects.
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.
Parameters
threadThread object to revoke access

◆ k_thread_perms_clear()

void k_thread_perms_clear ( struct k_object ko,
struct k_thread thread 
)

#include <zephyr/internal/syscall_handler.h>

Revoke a thread's permission to a kernel object.

Parameters
koKernel object metadata to update
threadThe thread to grant permission
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_thread_perms_inherit()

void k_thread_perms_inherit ( struct k_thread parent,
struct k_thread child 
)

#include <zephyr/internal/syscall_handler.h>

Copy all kernel object permissions from the parent to the child.

Parameters
parentParent thread, to get permissions from
childChild thread, to copy permissions to
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_thread_perms_set()

void k_thread_perms_set ( struct k_object ko,
struct k_thread thread 
)

#include <zephyr/internal/syscall_handler.h>

Grant a thread permission to a kernel object.

Parameters
koKernel object metadata to update
threadThe thread to grant permission
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_usermode_alloc_from_copy()

void * k_usermode_alloc_from_copy ( const void *  src,
size_t  size 
)

#include <zephyr/internal/syscall_handler.h>

Copy data from userspace into a resource pool allocation.

Given a pointer and a size, allocate a similarly sized buffer in the caller's resource pool and copy all the data within it to the newly allocated buffer. This will need to be freed later with k_free().

Checks are done to ensure that the current thread would have read access to the provided buffer.

Parameters
srcSource memory address
sizeSize of the memory buffer
Returns
An allocated buffer with the data copied within it, or NULL if some error condition occurred
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_usermode_from_copy()

int k_usermode_from_copy ( void *  dst,
const void *  src,
size_t  size 
)

#include <zephyr/internal/syscall_handler.h>

Copy data from user mode.

Given a userspace pointer and a size, copies data from it into a provided destination buffer, performing checks to ensure that the caller would have appropriate access when in user mode.

Parameters
dstDestination memory buffer
srcSource memory buffer, in userspace
sizeNumber of bytes to copy
Return values
0On success
EFAULTOn memory access error
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_usermode_string_alloc_copy()

char * k_usermode_string_alloc_copy ( const char *  src,
size_t  maxlen 
)

#include <zephyr/internal/syscall_handler.h>

Copy a C string from userspace into a resource pool allocation.

Given a C string and maximum length, duplicate the string using an allocation from the calling thread's resource pool. This will need to be freed later with k_free().

Checks are performed to ensure that the string is valid memory and that the caller has access to it in user mode.

Parameters
srcSource string pointer, in userspace
maxlenMaximum size of the string including trailing NULL
Returns
The duplicated string, or NULL if an error occurred.
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_usermode_string_copy()

int k_usermode_string_copy ( char *  dst,
const char *  src,
size_t  maxlen 
)

#include <zephyr/internal/syscall_handler.h>

Copy a C string from userspace into a provided buffer.

Given a C string and maximum length, copy the string into a buffer.

Checks are performed to ensure that the string is valid memory and that the caller has access to it in user mode.

Parameters
dstDestination buffer
srcSource string pointer, in userspace
maxlenMaximum size of the string including trailing NULL
Return values
0on success
EINVALif the source string is too long with respect to maxlen
EFAULTOn memory access error
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_usermode_string_nlen()

static size_t k_usermode_string_nlen ( const char *  src,
size_t  maxlen,
int *  err 
)
inlinestatic

#include <zephyr/internal/syscall_handler.h>

Obtain the size of a C string passed from user mode.

Given a C string pointer and a maximum size, obtain the true size of the string (not including the trailing NULL byte) just as if calling strnlen() on it, with the same semantics of strnlen() with respect to the return value and the maxlen parameter.

Any memory protection faults triggered by the examination of the string will be safely handled and an error code returned.

NOTE: Doesn't guarantee that user mode has actual access to this string, you will need to still do a K_SYSCALL_MEMORY_READ() with the obtained size value to guarantee this.

Parameters
srcString to measure size of
maxlenMaximum number of characters to examine
errPointer to int, filled in with -1 on memory error, 0 on success
Returns
undefined on error, or strlen(src) if that is less than maxlen, or maxlen if there were no NULL terminating characters within the first maxlen bytes.
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.

◆ k_usermode_to_copy()

int k_usermode_to_copy ( void *  dst,
const void *  src,
size_t  size 
)

#include <zephyr/internal/syscall_handler.h>

Copy data to user mode.

Given a userspace pointer and a size, copies data to it from a provided source buffer, performing checks to ensure that the caller would have appropriate access when in user mode.

Parameters
dstDestination memory buffer, in userspace
srcSource memory buffer
sizeNumber of bytes to copy
Return values
0On success
EFAULTOn memory access error
Note
This is an internal API. Do not use unless you are extending functionality in the Zephyr tree.