~ubuntu-branches/ubuntu/precise/manpages-posix/precise

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 

.TH "POSIX_TYPED_MEM_OPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"

.\" posix_typed_mem_open 

.SH NAME

posix_typed_mem_open \- open a typed memory object (\fBADVANCED REALTIME\fP)

.SH SYNOPSIS

.LP

\fB#include <sys/mman.h>

.br

.sp

int posix_typed_mem_open(const char *\fP\fIname\fP\fB, int\fP \fIoflag\fP\fB,

int\fP \fItflag\fP\fB); \fP

\fB

.br

\fP

.SH DESCRIPTION

.LP

The \fIposix_typed_mem_open\fP() function shall establish a connection

between the typed memory object specified by the string

pointed to by \fIname\fP and a file descriptor. It shall create an

open file description that refers to the typed memory object

and a file descriptor that refers to that open file description. The

file descriptor is used by other functions to refer to that

typed memory object. It is unspecified whether the name appears in

the file system and is visible to other functions that take

pathnames as arguments. The \fIname\fP argument shall conform to the

construction rules for a pathname. If \fIname\fP begins with

the slash character, then processes calling \fIposix_typed_mem_open\fP()

with the same value of \fIname\fP shall refer to the

same typed memory object. If \fIname\fP does not begin with the slash

character, the effect is implementation-defined. The

interpretation of slash characters other than the leading slash character

in \fIname\fP is implementation-defined.

.LP

Each typed memory object supported in a system shall be identified

by a name which specifies not only its associated typed

memory pool, but also the path or port by which it is accessed. That

is, the same typed memory pool accessed via several different

ports shall have several different corresponding names. The binding

between names and typed memory objects is established in an

implementation-defined manner. Unlike shared memory objects, there

is no way within IEEE\ Std\ 1003.1-2001 for a program to

create a typed memory object.

.LP

The value of \fItflag\fP shall determine how the typed memory object

behaves when subsequently mapped by calls to \fImmap\fP(). At most,

one of the following flags defined in \fI<sys/mman.h>\fP may be specified:

.TP 7

POSIX_TYPED_MEM_ALLOCATE

Allocate on \fImmap\fP().

.TP 7

POSIX_TYPED_MEM_ALLOCATE_CONTIG

Allocate contiguously on \fImmap\fP().

.TP 7

POSIX_TYPED_MEM_MAP_ALLOCATABLE

Map on \fImmap\fP(), without affecting allocatability.

.sp

.LP

If \fItflag\fP has the flag POSIX_TYPED_MEM_ALLOCATE specified, any

subsequent call to \fImmap\fP() using the returned file descriptor

shall result in allocation and mapping of typed

memory from the specified typed memory pool. The allocated memory

may be a contiguous previously unallocated area of the typed

memory pool or several non-contiguous previously unallocated areas

(mapped to a contiguous portion of the process address space).

If \fItflag\fP has the flag POSIX_TYPED_MEM_ALLOCATE_CONTIG specified,

any subsequent call to \fImmap\fP() using the returned file descriptor

shall result in allocation and mapping of a single

contiguous previously unallocated area of the typed memory pool (also

mapped to a contiguous portion of the process address space).

If \fItflag\fP has none of the flags POSIX_TYPED_MEM_ALLOCATE or POSIX_TYPED_MEM_ALLOCATE_CONTIG

specified, any subsequent call to

\fImmap\fP() using the returned file descriptor shall map an application-chosen

area from the

specified typed memory pool such that this mapped area becomes unavailable

for allocation until unmapped by all processes. If

\fItflag\fP has the flag POSIX_TYPED_MEM_MAP_ALLOCATABLE specified,

any subsequent call to \fImmap\fP() 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. The appropriate privilege to specify the POSIX_TYPED_MEM_MAP_ALLOCATABLE

flag is implementation-defined.

.LP

If successful, \fIposix_typed_mem_open\fP() shall return a file descriptor

for the typed memory object that is the lowest

numbered file descriptor not currently open for that process. The

open file description is new, and therefore the file descriptor

shall not share it with any other processes. It is unspecified whether

the file offset is set. The FD_CLOEXEC file descriptor flag

associated with the new file descriptor shall be cleared.

.LP

The behavior of \fImsync\fP(), \fIftruncate\fP(), and all file operations

other than \fImmap\fP(), \fIposix_mem_offset\fP(), \fIposix_typed_mem_get_info\fP(),

\fIfstat\fP(), \fIdup\fP(), \fIdup2\fP(), and \fIclose\fP(), is unspecified

when passed a

file descriptor connected to a typed memory object by this function.

.LP

The file status flags of the open file description shall be set according

to the value of \fIoflag\fP. Applications shall

specify exactly one of the three access mode values described below

and defined in the \fI<fcntl.h>\fP header, as the value of \fIoflag\fP.

.TP 7

O_RDONLY

Open for read access only.

.TP 7

O_WRONLY

Open for write access only.

.TP 7

O_RDWR

Open for read or write access.

.sp

.SH RETURN VALUE

.LP

Upon successful completion, the \fIposix_typed_mem_open\fP() function

shall return a non-negative integer representing the

lowest numbered unused file descriptor. Otherwise, it shall return

-1 and set \fIerrno\fP to indicate the error.

.SH ERRORS

.LP

The \fIposix_typed_mem_open\fP() function shall fail if:

.TP 7

.B EACCES

The typed memory object exists and the permissions specified by \fIoflag\fP

are denied.

.TP 7

.B EINTR

The \fIposix_typed_mem_open\fP() operation was interrupted by a signal.

.TP 7

.B EINVAL

The flags specified in \fItflag\fP are invalid (more than one of POSIX_TYPED_MEM_ALLOCATE,

POSIX_TYPED_MEM_ALLOCATE_CONTIG, or

POSIX_TYPED_MEM_MAP_ALLOCATABLE is specified).

.TP 7

.B EMFILE

Too many file descriptors are currently in use by this process.

.TP 7

.B ENAMETOOLONG

The length of the \fIname\fP argument exceeds {PATH_MAX} or a pathname

component is longer than {NAME_MAX}.

.TP 7

.B ENFILE

Too many file descriptors are currently open in the system.

.TP 7

.B ENOENT

The named typed memory object does not exist.

.TP 7

.B EPERM

The caller lacks the appropriate privilege to specify the flag POSIX_TYPED_MEM_MAP_ALLOCATABLE

in argument \fItflag\fP.

.sp

.LP

\fIThe following sections are informative.\fP

.SH EXAMPLES

.LP

None.

.SH APPLICATION USAGE

.LP

None.

.SH RATIONALE

.LP

None.

.SH FUTURE DIRECTIONS

.LP

None.

.SH SEE ALSO

.LP

\fIclose\fP() , \fIdup\fP() , \fIexec\fP() , \fIfcntl\fP() , \fIfstat\fP()

,

\fIftruncate\fP() , \fImmap\fP() , \fImsync\fP() ,

\fIposix_mem_offset\fP() , \fIposix_typed_mem_get_info\fP() , \fIumask\fP()

, the Base

Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<fcntl.h>\fP, \fI<sys/mman.h>\fP

.SH COPYRIGHT

Portions of this text are reprinted and reproduced in electronic form

from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology

-- Portable Operating System Interface (POSIX), The Open Group Base

Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of

Electrical and Electronics Engineers, Inc and The Open Group. In the

event of any discrepancy between this version and the original IEEE and

The Open Group Standard, the original IEEE and The Open Group Standard

is the referee document. The original Standard can be obtained online at

http://www.opengroup.org/unix/online.html .