shm_create_subrange

Synopsis:

#include <fcntl.h>
#include <sys/mman.h>

int shm_create_subrange_handle( int const fd, 
                       pid_t const pid, 
                       int const flags,
                       shm_handle_t* const handlep,
                       unsigned options,
                       size_t const size,
                       off_t const offset);

Arguments:

fd

Open shared memory object. This file descriptor can be created first by open(), shm_open(), or shm_open_handle().

pid

The ID of the process that you want to access the shared object.

flags

Access mode for the target process (O_flags). You must specify exactly one of the following file access modes (defined in <fcntl.h>) in the value of flags:

O_RDONLY — open for read access only.
O_RDWR — open for read and write access.
O_WRONLY — open for write access only.

Note:

For the function call to succeed, the flags must specify an access mode with the same or lower privileges than the mode specified when creating a new memory object with shm_open().

Setting a more privileged access mode or any flags other than the ones listed above causes the function call to fail.

handlep

Holds the generated handle, upon return.

options

A bitmask configuring options for the shared object. Currently, the only supported flag is:

SHM_CREATE_HANDLE_OPT_NOFD — prevent the shared memory object handle from being converted to a file descriptor using shm_open_handle(). This improves security because the creator can share an object with a recipient process but then later revoke access. This flag is meant to be used after setting the SHMCTL_REVOCABLE flag on the object via shm_ctl(), and before giving the handle to the recipient.

size

Size of the subrange in bytes. Must be a multiple of page size.

offset

Offset from the beginning of the object pointed to by fd. Must be a multiple of page size.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

Returns a unique handle for a shared-memory object. The handle can be used by the target process identified by the pid parameter to either obtain a file descriptor via a call to shm_open_handle() or to perform a mapping via shm_mmap_handle().

Returns:

0 on success, or -1 if an error occurred (errno is set).

Errors:

EACCES: Permission to create the handle is denied because the access modes specified by flags are denied.
EAGAIN: The process has created a number of handles that have not been consumed (opened, mapped, or deleted) greater than its allowed limit specified for RLIMIT_SHM_HANDLES_NP (refer to prlimit()).
EBADF: The specified file descriptor doesn't exist.
EINVAL: An illegal flag, meaning a flag other than one indicating the access mode, was given in flags (see the parameter description).
ENOMEM: There's insufficient memory to create a shared object handle.
ESRCH: The process ID in pid is invalid.

Classification:

QNX OS


Safety:
Cancellation point	No
Signal handler	Yes
Thread	Yes

shm_create_subrange_handle()