shm_open_handle()

Arguments:

handle

A handle created for the calling process by shm_create_handle().

flags

A combination of the following bits (defined in <fcntl.h>):

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

Note: You can also specify O_CLOEXEC but this flag has no effect because it's always set (see below). Setting any other flags causes the function call to fail.

Library:

libc

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

Description:

The shm_open_handle() function returns a file descriptor that's associated with the shared memory object specified by handle. This file descriptor can be used by other functions to refer to the shared memory object (e.g., mmap()). The FD_CLOEXEC flag in fcntl() is automatically set for this file descriptor.

The handle argument must have been created with shm_create_handle() specifically for the calling process (i.e., the recipient). This is typically (but doesn't have to be) done in another process. For an example of how a client can request the creation of a handle from a server and then use that handle to access the shared memory, see below.

The state of the shared memory object, including all data associated with it, persists until the object is unlinked and all other references are gone.

Returns:

A nonnegative integer, which is the lowest numbered unused file descriptor, or -1 if an error occurred (errno is set).

Errors:

EACCES

Permission to access the shared memory object is denied because the access modes specified by flags are denied.

EAGAIN

There are insufficient resources to complete the operation.

EINVAL

An illegal flag, meaning a flag other than one indicating the access mode, was given in flags (see the parameter description).

EMFILE

All file descriptors available to the process are currently open.

ENFILE

Too many shared memory objects are currently open in the system.

ENOMEM

There's insufficient memory to open a file descriptor.

ESRCH

The specified handle does not exist.

Example:

int fd, shm_fd;
// Your application will likely have its own data structure for representing messages
// to send to the server.
mymsg_t msg;
shm_handle_t handle;
void* ptr;

// Connect to the server.
fd = open("/path/to/server", O_RDWR);

// The code for handling a failed open attempt and for populating the message structure
// (assuming the open did not fail) goes here.

// Ask the server for a handle.
MsgSend(fd, &msg, sizeof(msg), &handle, sizeof(handle));

// Convert the handle to a file descriptor.
shm_fd = shm_open_handle(handle, O_RDWR);

// Map the shared memory object into the client's space.
// The memory region mapped in is equal in size to one memory page, can be read
// but not written by the calling process, and can be shared with other processes.
ptr = mmap(0, __PAGESIZE, PROT_READ, MAP_SHARED, shm_fd, 0);

Classification:

QNX Neutrino