posix_typed_mem_get_info()

Updated: April 19, 2023

Get information about a typed memory object

Synopsis:

#include <sys/mman.h>

int posix_typed_mem_get_info(
        int filedes,
        struct posix_typed_mem_info *info);

Arguments:

filedes
The file descriptor for the typed memory object that you want to query, returned by a call to posix_typed_mem_open().
info
A pointer to a posix_typed_mem_info structure where the function can store the information.

Library:

libc

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

Description:

The posix_typed_mem_get_info() function queries the specified typed memory object to obtain the size of the largest possible allocation. This is particularly important for typed memory objects that may in some cases be scarce resources.

If you opened the object with POSIX_TYPED_MEM_ALLOCATE, this function reports the amount of free space available, because you're requesting the largest possible allocation in non-contiguous memory, which is one that consumes all available memory. If you opened the object with POSIX_TYPED_MEM_ALLOCATE_CONTIG, this function reports the largest contiguous allocation available. Note, though, that we don't search physical memory for the largest contiguous chunk within a single 16MB zone. As a result, when there is less than 16MB contiguous memory available, the function reports 4KB (a page size) when in fact there may be a larger chunk available.

If you specified any other flag when opening the object, the reported maximum allocation length is 0. As a QNX Neutrino extension, if you opened the object with neither POSIX_TYPED_MEM_ALLOCATE nor POSIX_TYPED_MEM_ALLOCATE_CONTIG, the function sets info->posix_tmi_length to 0.

Note: If the typed memory pool is a shared resource, some form of mutual-exclusion or synchronization may be required while querying and allocating it, to prevent race conditions.

The maximum length is dynamic; it's valid only while the current mapping of the corresponding typed memory pool remains unchanged. Because the mapping can change at any time, the result of this function is statistical and can't be relied upon for any other purpose.

posix_typed_mem_info

Structure that describes a typed memory object in terms of total size and amount of memory available:

struct __posix_typed_mem_info64 {
  _Uint64t            posix_tmi_length;
  _Uint64t            __posix_tmi_total;
  _Uint32t            __reserved[2];
};

It contains the following fields:

posix_tmi_length
Field that stores the maximum amount of memory that can be allocated by the typed memory object (POSIX-mandated).
_posix_tmi_total
QNX extension to provide the size of an object (i.e., the total amount of memory it holds).

Returns:

0
Success.
EBADF
The filedes argument isn't a valid open file descriptor.
ENODEV
The filedes isn't connected to a memory object supported by this function.

Classification:

POSIX 1003.1 TYM

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