shm_ctl_special()

Synopsis:

#include <sys/mman.h>

int shm_ctl_special( int fd,
             int flags,
             uint64_t paddr,
             uint64_t size,
             unsigned special );

Since:

BlackBerry 10.0.0

Arguments:

fd

The file descriptor that's associated with the shared memory object, as returned by shm_open() .

flags

One or more of the following bits, defined in <sys/mman.h>:

SHMCTL_ANON — allocate anonymous memory.
SHMCTL_GLOBAL — a hint that any mapping to the object could be global across all processes.
Note: In order to use the SHMCTL_GLOBAL flag, your process must have the PROCMGR_AID_MEM_GLOBAL ability enabled. For more information, see procmgr_ability() .
SHMCTL_HIGHUSAGE — a hint that the object is used a lot, and so the system should try to do things to speed up access to it.
SHMCTL_ISADMA — memory should be suitable for ISA DMA (e.g. it should be below 16 MB, and shouldn't cross 64 KB boundaries).
SHMCTL_LAZY — delay allocating the memory until it's referenced.
If you create anonymous shared memory objects (by calling mmap() with MAP_ANON | MAP_SHARED and a file descriptor of -1), a MAP_LAZY flag implicitly sets the SHMCTL_LAZY flag on the object.
SHMCTL_LAZYWRITE — a hint that a mapping of this object could use lazy-writing mechanisms.
SHMCTL_LOWERPROT — a hint that the system may map this object in such a way that it trades lower memory protection for better performance.
SHMCTL_NODEFRAG — used with SHMCTL_PHYS | SHMCTL_ANON to specify that you want physically contiguous memory, but not so much that you're willing to wait for defragmentation. If contiguous memory isn't immediately available, the call gives an error of ENOMEM, and you can retry with just SHMCTL_ANON if you're willing to accept discontiguity.
SHMCTL_NOX64K — memory shouldn't cross 64 KB boundaries.
SHMCTL_PHYS — use physical address, or allocate physically contiguous memory if used with SHMCTL_ANON.
Note: In order to use the SHMCTL_PHYS flag, your process must have the PROCMGR_AID_MEM_PHYS ability enabled. For more information, see procmgr_ability() .
SHMCTL_PRIV — a hint that a mapping of this object may require privileged access.

SHMCTL_REPEAT — create a strided physical object. For example:

shm_ctl( fd, SHMCTL_PHYS, baseaddr, vstride );
shm_ctl( fd, SHMCTL_REPEAT, pstride, count );

Note: Some of the above bits have specific meanings for different processors. For more information, see the documentation for shm_ctl() .

paddr

A physical address to assign to the object, if you set SHMCTL_PHYS in flags.

size

The new size of the object, in bytes, regardless of the ANON/PHYS flag.

special

Processor-specific flags; see the following sections below:

ARM-specific flags

Library:

libc

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

Description:

The shm_ctl_special() function modifies the attributes of the shared memory object identified by the handle, fd. This handle is the value returned by shm_open() .

The shm_ctl_special() function is similar to shm_ctl() , but has an additional processor-specific argument, special.

Note:

In order to call shm_ctl_special(), your process must have the PROCMGR_AID_MEM_SPECIAL ability enabled. For more information, see procmgr_ability() .
Calling shm_ctl_special() with a special argument of 0 isn't equivalent to calling shm_ctl(). There's an internal flag that tells the memory manager which function you called, so it can treat shared objects differently. Specifying 0 for special could clear some special bits that are on by default.
The combination SHMCTL_ANON | SHMCTL_PHYS has the same behavior as for mmap() : it indicates that you want physically contiguous RAM to be allocated for the object.
On ARM targets, once you've called shm_ctl() for a shared memory object, you can't resize it. You must unmap and unlink the shared object, and then recreate it.
If you specify SHMCTL_PHYS in the flags, then paddr and size must be even multiples of the page size (sysconf(_SC_PAGE_SIZE)).

ARM-specific flags

For ARM platforms, the special argument specifies the page table entry (PTE) bits to be set when the object is mapped. These bits and their meaning are generally processor-specific:

For ARMv6 processors, you can specify the following:

cacheable (ARM_PTE_C)
bufferable (ARM_PTE_B)
execute-never (ARM_PTE_V6_SP_XN)
TEX encoding (ARM_PTE_V5_SP_TEX(x))
sharable (ARM_PTE_V6_S)

Returns:

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

Errors:

EAGAIN

The special value doesn't match the current special value.

EBADF

The shared memory object is already "special."

EINVAL

An invalid combination of flags was specified.

ENOMEM

One of the following:

There wasn't enough memory.
You specified SHMCTL_PHYS | SHMCTL_ANON | SHMCTL_NODEFRAG, and contiguous memory wasn't immediately available. You can retry with just SHMCTL_ANON if you're willing to accept discontiguity.

EPERM

The calling process doesn't have the required permission; see procmgr_ability() .

Classification:

QNX Neutrino

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