shm_revoke()

Updated: April 19, 2023

Revoke mappings to shared memory

Synopsis:

#include <sys/mman.h>

int shm_revoke( int fd,
                pid_t pid );

Arguments:

fd
A file descriptor, belonging to the creator, for the shared memory object. It doesn't have to be the file descriptor that was used to create the object.
pid
The process ID to revoke mappings for, or -1 to revoke mappings for all processes, including the object's creator.

Library:

libc

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

Description:

The shm_revoke() function allows a process that created a shared memory object to dissociate the backing memory from mappings on the object, essentially revoking access to the backing memory made possible through these mappings. This function also destroys any unused handles given to the recipient for the object.

Only the object's creator can successfully call this function. The creator is the process with the same process ID as the one that created the object via shm_open(); if that process calls fork(), the new process isn't considered to be the object's creator.

The creator must have marked the access as revocable by calling shm_ctl() with SHMCTL_REVOCABLE set in the flags argument. Only mappings created after the shared memory object has been marked as revocable are revoked; prior existing mappings aren't affected. Mappings are revoked for the entire object, not just to the pieces that SHMCTL_REVOCABLE was specified for.

In order to prevent a recipient from protecting itself against revocation by forking, revocable object regions are marked as MAP_NOINHERIT (see mmap()) and thus are ignored if the recipient forks; the memory maps for revocable objects won't exist in the child.

To retain the most control over the object, the creator must give other processes a handle that can't be converted into a file descriptor. This involves the following:

For more details, see Secure buffer management in the “Shared Memory” chapter of the QNX Neutrino Programmer's Guide.

Returns:

0
Success.
-1
An error occurred (errno is set).

Errors:

EINVAL
The object wasn't tagged with SHMCTL_REVOCABLE.
EPERM
The caller isn't the creator of the object.
ESRCH
The process represented by pid doesn't exist.

Classification:

QNX Neutrino

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes