Open a typed memory object
#include <sys/mman.h> #include <fcntl.h> int posix_typed_mem_open( const char * name, int oflag, int tflag);
- A pointer to the string that specifies the typed memory object.
- The access mode to use; one of:
- Open for read access only.
- Open for write access only.
- Open for read or write access.
- Flags that determine how the typed memory object behaves when mapped;
at most one of:
- Allocate on mmap().
- Allocate contiguously on mmap().
- Map on mmap() without affecting the availability for allocation.
Use the -l c option to qcc to link against this library. This library is usually included automatically.
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 names of typed memory regions are derived directly from the names of the asinfo segments. The asinfo section itself describes a hierarchy, and so the naming of typed memory object is a hierarchy.
The posix_typed_mem_open() function resolves the name as follows:
- If the name starts with a leading /, an exact match is done.
- The name may contain intermediate / characters. These are considered as path component separators. If multiple path components are specified, they're matched from the bottom up (the opposite of the way filenames are resolved).
- If the name doesn't start with a leading /, a tail match is done on the pathname components specified.
For more information, see Typed memory in the Interprocess Communication (IPC) chapter of the System Architecture guide.
The file descriptor is used by other functions to refer to that typed memory object.
The setting of tflag affects what happens when you call mmap() with the file descriptor for the typed memory object:
- The mmap() function allocates and maps typed memory from the specified typed memory pool. The allocated memory is either a previously unallocated contiguous area of the typed memory pool, or several noncontiguous previously unallocated areas (mapped to a contiguous portion of the process address space).
- The mmap() function allocates and maps a previously unallocated single contiguous area of the typed memory pool (also mapped to a contiguous portion of the process address space).
- Neither POSIX_TYPED_MEM_ALLOCATE nor POSIX_TYPED_MEM_ALLOCATE_CONTIG
- The mmap() function maps an application-chosen area from
the specified typed memory pool.
The mapped area is unavailable for allocation until all processes unmap it.
- The mmap() function maps an application-chosen area from the specified typed memory pool without affecting 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 tflag is 0 or POSIX_TYPED_MEM_MAP_ALLOCATABLE, the offset parameter to mmap() specifies the starting physical address in the typed memory region; if the typed memory region is discontiguous (multiple asinfo entries), the allowed offset values are also discontiguous and don't start at zero as they do for shared memory objects. If you specify a [paddr, paddr + size) region that falls outside the allowed addresses for the typed memory object, mmap() fails with ENXIO.
The oflag controls what permissions you're allowed to mmap() with. For example, if oflag is O_RDONLY, you can't do a mmap() with MAP_SHARED and PROT_WRITE.
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 isn't shared with any other processes. The FD_CLOEXEC file descriptor flag associated with the new file descriptor is cleared.
As Neutrino extensions:
A nonnegative integer that represents the lowest-numbered unused file descriptor, or -1 if an error occurred (errno is set).
- The typed memory object exists, and the permissions specified by oflag are denied.
- The posix_typed_mem_open() function was interrupted by a signal.
- The flags specified in tflag are invalid (more than one of POSIX_TYPED_MEM_ALLOCATE, POSIX_TYPED_MEM_ALLOCATE_CONTIG, and POSIX_TYPED_MEM_MAP_ALLOCATABLE is specified).
- Too many file descriptors are currently in use by this process.
- The length of the name argument exceeds PATH_MAX, or a pathname component is longer than NAME_MAX.
- Too many file descriptors are currently open in the system.
- The named typed memory object doesn't exist.
- The caller lacks the superuser capability to specify the flag POSIX_TYPED_MEM_MAP_ALLOCATABLE in the tflag argument.