[Previous] [Contents] [Index] [Next]

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
Point to the string that specifies the typed memory object.
oflag
Flag of the open file description that deterrmine the file status.
tflag
Flag that determine how the typed memory object behaves when mapped.

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 string pointed to by 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.

Set the file status flags of the open file description according to the value of oflag as specified below:

O_RDONLY
Open for read access only.
O_WRONLY
Open for write access only.
O_RDWR
Open for read or write access.

The value of tflag determine how the typed memory object behaves when subsequently mapped by calls to mmap(). It can take one of the following values:

POSIX_TYPED_MEM_ALLOCATE
Allocate on mmap().
POSIX_TYPED_MEM_ALLOCATE_CONTIG
Allocate contiguously on mmap().
POSIX_TYPED_MEM_MAP_ALLOCATABLE
Map on mmap() that doesn't affect allocation.

If name begins with the slash character, then processes calling posix_typed_mem_open() with the same value of name shall refer to the same typed memory object. If name doesn't begin with the slash character, the effect is implementation-defined (?). The interpretation of slash characters other than the leading slash character in name is implementation-defined (?).

When tflag is set to POSIX_TYPED_MEM_ALLOCATE, any subsequent call to mmap() that uses the returned file descriptor shall result in 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) non-contiguous 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 shall result in 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 is not set to either POSIX_TYPED_MEM_ALLOCATE or POSIX_TYPED_MEM_ALLOCATE_CONTIG, any subsequent call to mmap() that uses the returned file descriptor shall map 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 specified, any subsequent call to mmap() using the returned file descriptor shall map 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 shall be 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 unspecified when passed a file descriptor connected to a typed memory object by this function. The file status flags of the open file description shall be set according to the value of oflag. Applications shall specify exactly one of the three access mode values described below and defined in the header, as the value of oflag.


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.
Success.
-1
An error has 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 is 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_typed_mem_open() is POSIX 1003.1-2001

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

See also:

posix_typed_mem_get_info(), posix_mem_offset()


[Previous] [Contents] [Index] [Next]