2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
2007-06-20 22:33:04 +00:00
|
|
|
.TH "POSIX_TYPED_MEM_GET_INFO" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" posix_typed_mem_get_info
|
2007-09-20 06:03:25 +00:00
|
|
|
.SH PROLOG
|
|
|
|
This manual page is part of the POSIX Programmer's Manual.
|
|
|
|
The Linux implementation of this interface may differ (consult
|
|
|
|
the corresponding Linux manual page for details of Linux behavior),
|
|
|
|
or the interface may not be implemented on Linux.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
posix_typed_mem_get_info \- query typed memory information (\fBADVANCED
|
|
|
|
REALTIME\fP)
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.LP
|
|
|
|
\fB#include <sys/mman.h>
|
|
|
|
.br
|
|
|
|
.sp
|
|
|
|
int posix_typed_mem_get_info(int\fP \fIfildes\fP\fB,
|
|
|
|
.br
|
|
|
|
\ \ \ \ \ \ struct posix_typed_mem_info *\fP\fIinfo\fP\fB); \fP
|
|
|
|
\fB
|
|
|
|
.br
|
|
|
|
\fP
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.LP
|
|
|
|
The \fIposix_typed_mem_get_info\fP() function shall return, in the
|
|
|
|
\fIposix_tmi_length\fP field of the
|
|
|
|
\fBposix_typed_mem_info\fP structure pointed to by \fIinfo\fP, the
|
|
|
|
maximum length which may be successfully allocated by the
|
|
|
|
typed memory object designated by \fIfildes\fP. This maximum length
|
|
|
|
shall take into account the flag POSIX_TYPED_MEM_ALLOCATE or
|
|
|
|
POSIX_TYPED_MEM_ALLOCATE_CONTIG specified when the typed memory object
|
|
|
|
represented by \fIfildes\fP was opened. The maximum length
|
|
|
|
is dynamic; therefore, the value returned is valid only while the
|
|
|
|
current mapping of the corresponding typed memory pool remains
|
|
|
|
unchanged.
|
|
|
|
.LP
|
|
|
|
If \fIfildes\fP represents a typed memory object opened with neither
|
|
|
|
the POSIX_TYPED_MEM_ALLOCATE flag nor the
|
|
|
|
POSIX_TYPED_MEM_ALLOCATE_CONTIG flag specified, the returned value
|
|
|
|
of \fIinfo\fP->\fIposix_tmi_length\fP is unspecified.
|
|
|
|
.LP
|
|
|
|
The \fIposix_typed_mem_get_info\fP() function may return additional
|
|
|
|
implementation-defined information in other fields of the
|
|
|
|
\fBposix_typed_mem_info\fP structure pointed to by \fIinfo\fP.
|
|
|
|
.LP
|
|
|
|
If the memory object specified by \fIfildes\fP is not a typed memory
|
|
|
|
object, then the behavior of this function is
|
|
|
|
undefined.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
.LP
|
|
|
|
Upon successful completion, the \fIposix_typed_mem_get_info\fP() function
|
|
|
|
shall return zero; otherwise, the corresponding error
|
|
|
|
status value shall be returned.
|
|
|
|
.SH ERRORS
|
|
|
|
.LP
|
|
|
|
The \fIposix_typed_mem_get_info\fP() function shall fail if:
|
|
|
|
.TP 7
|
|
|
|
.B EBADF
|
|
|
|
The \fIfildes\fP argument is not a valid open file descriptor.
|
|
|
|
.TP 7
|
|
|
|
.B ENODEV
|
|
|
|
The \fIfildes\fP argument is not connected to a memory object supported
|
|
|
|
by this function.
|
|
|
|
.sp
|
|
|
|
.LP
|
|
|
|
This function shall not return an error code of [EINTR].
|
|
|
|
.LP
|
|
|
|
\fIThe following sections are informative.\fP
|
|
|
|
.SH EXAMPLES
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH APPLICATION USAGE
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH RATIONALE
|
|
|
|
.LP
|
|
|
|
An application that needs to allocate a block of typed memory with
|
|
|
|
length dependent upon the amount of memory currently
|
|
|
|
available must either query the typed memory object to obtain the
|
|
|
|
amount available, or repeatedly invoke \fImmap\fP() attempting to
|
|
|
|
guess an appropriate length. While the latter method is existing practice
|
|
|
|
with \fImalloc\fP(), it is awkward and imprecise. The \fIposix_typed_mem_get_info\fP()
|
|
|
|
function allows an application to immediately determine available
|
|
|
|
memory. This is particularly important for typed memory objects
|
|
|
|
that may in some cases be scarce resources. Note that when a typed
|
|
|
|
memory pool is a shared resource, some form of mutual-exclusion
|
|
|
|
or synchronization may be required while typed memory is being queried
|
|
|
|
and allocated to prevent race conditions.
|
|
|
|
.LP
|
|
|
|
The existing \fIfstat\fP() function is not suitable for this purpose.
|
|
|
|
We realize that
|
|
|
|
implementations may wish to provide other attributes of typed memory
|
|
|
|
objects (for example, alignment requirements, page size, and
|
|
|
|
so on). The \fIfstat\fP() function returns a structure which is not
|
|
|
|
extensible and,
|
|
|
|
furthermore, contains substantial information that is inappropriate
|
|
|
|
for typed memory objects.
|
|
|
|
.SH FUTURE DIRECTIONS
|
|
|
|
.LP
|
|
|
|
None.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.LP
|
2007-09-20 06:11:55 +00:00
|
|
|
\fIfstat\fP(), \fImmap\fP(), \fIposix_typed_mem_open\fP(), the
|
2004-11-03 13:51:07 +00:00
|
|
|
Base Definitions volume of IEEE\ Std\ 1003.1-2001, \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 .
|