shm_revoke()
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.
After this function is called, if the recipient process whose PID matches pid, or any process if -1 was given for pid, tries to access the shared memory object, the access fails and that process receives a SIGSEGV.
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:
- Creating an anonymous shared memory object by using the SHM_ANON flag for shm_open().
- Setting the SHMCTL_REVOCABLE flag with shm_ctl().
- Using the SHM_CREATE_HANDLE_OPT_NOFD option for shm_create_handle() to create a single-use handle that's for a specific process and that can't be converted into a file descriptor. The recipient then has to use mmap_handle() instead of mmap().
- Using shm_revoke() to revoke a recipient's mappings of the object.
For more details, see
Secure buffer management
in the Shared Memory
chapter of the QNX OS 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:
| Safety: | |
|---|---|
| Cancellation point | No |
| Signal handler | Yes |
| Thread | Yes |