diff options
Diffstat (limited to 'man3p/posix_typed_mem_get_info.3p')
| -rw-r--r-- | man3p/posix_typed_mem_get_info.3p | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/man3p/posix_typed_mem_get_info.3p b/man3p/posix_typed_mem_get_info.3p new file mode 100644 index 000000000..d9a7ff0c3 --- /dev/null +++ b/man3p/posix_typed_mem_get_info.3p @@ -0,0 +1,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 . |