1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
.TH "POSIX_TYPED_MEM_GET_INFO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" posix_typed_mem_get_info
.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
\fIfstat\fP() , \fImmap\fP() , \fIposix_typed_mem_open\fP() , the
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 .
|
