Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

posix_typed_mem_open()

Open a typed memory object

Synopsis:

#include <sys/mman.h>

int posix_typed_mem_open(const char * name,
                         int oflag,
                         intt * tflag);

Arguments:

name
A pointer to the string that specifies the typed memory object.
oflag
The access mode to use; one of:
O_RDONLY
Open for read access only.
O_WRONLY
Open for write access only.
O_RDWR
Open for read or write access.
tflag
Flag that determine how the typed memory object behaves when mapped; at most one of:
POSIX_TYPED_MEM_ALLOCATE
Allocate on mmap().
POSIX_TYPED_MEM_ALLOCATE_CONTIG
Allocate contiguously on mmap().
POSIX_TYPED_MEM_MAP_ALLOCATABLE
Map on mmap() without affecting the availability for allocation.

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_open() function establishes a connection between the typed memory object specified by the name and a file descriptor. It creates an open file description that refers to the typed memory object and a file descriptor that refers to the open file description.

The file descriptor is used by other functions to refer to that typed memory object.

The QNX Neutrino refers to the same typed memory object whether the name begins with the slash character or not, i.e. /sysram and sysram refer to the same typed memory object.

When tflag is set to POSIX_TYPED_MEM_ALLOCATE, any subsequent call to mmap() that uses the returned file descriptor shall result in the allocation and mapping of typed memory from the specified typed memory pool. The allocated memory will be either of the previously unallocated contiguous area of the typed memory pool or previously unallocated (several) noncontiguous areas (mapped to a contiguous portion of the process address space).

When tflag is set to POSIX_TYPED_MEM_ALLOCATE_CONTIG, any subsequent call to mmap() that uses the returned file descriptor results in the allocation and mapping of a previously unallocated single contiguous area of the typed memory pool (also mapped to a contiguous portion of the process address space).

If tflag isn't set to either POSIX_TYPED_MEM_ALLOCATE or POSIX_TYPED_MEM_ALLOCATE_CONTIG, any subsequent call to mmap() that uses the returned file descriptor maps an application-chosen area from the specified typed memory pool. Note that this mapped area becomes unavailable for allocation until unmapped by all processes.

When tflag is set to POSIX_TYPED_MEM_MAP_ALLOCATABLE, any subsequent call to mmap() using the returned file descriptor maps an application-chosen area from the specified typed memory pool without an effect on the availability of that area for allocation; that is, mapping such an object leaves each byte of the mapped area unallocated if it was unallocated prior to the mapping or allocated if it was allocated prior to the mapping.

If successful, posix_typed_mem_open() returns a file descriptor for the typed memory object that is the lowest numbered file descriptor not currently open for that process. The open file descriptor is new, and therefore the file descriptor won't share it with any other processes. The FD_CLOEXEC file descriptor flag associated with the new file descriptor is cleared.

The behavior of msync(), ftruncate(), and all file operations other than mmap(), posix_mem_offset(), posix_typed_mem_get_info(), fstat(), dup(), dup2(), and close() is as follows (see the next paragraph) when passed a file descriptor connected to a typed memory object by this function. The file status flags of the open file description is set according to the value of oflag.

The msync() function performs the QNX extension, i.e. it flushes and/or invalidates data and or instruction cache for the specified memory region.

All other functions return error with ENOSYS.


Note:

This function was added in the QNX Neutrino Core OS 6.3.2.


Returns:

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

Errors:

EACCES
The typed memory object exists and the permissions specified by oflag are denied.
EINTR
The posix_typed_mem_open() API was interrupted by a signal.
EINVAL
The flags specified in tflag are invalid (more than one of POSIX_TYPED_MEM_ALLOCATE, POSIX_TYPED_MEM_ALLOCATE_CONTIG, or POSIX_TYPED_MEM_MAP_ALLOCATABLE is specified).
EMFILE
Too many file descriptors are currently in use by this process.
ENAMETOOLONG
The length of the name argument exceeds PATH_MAX or a pathname component is longer than NAME_MAX.
ENFILE
Too many file descriptors are currently open in the system.
ENOENT
The named typed memory object doesn't exist.
EPERM
The caller lacks the superuser capability to specify the flag POSIX_TYPED_MEM_MAP_ALLOCATABLE in argument tflag.

Classification:

POSIX 1003.1

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

See also:

posix_typed_mem_get_info(), posix_mem_offset()