diff options
Diffstat (limited to 'man3/posix_memalign.3')
| -rw-r--r-- | man3/posix_memalign.3 | 279 |
1 files changed, 279 insertions, 0 deletions
diff --git a/man3/posix_memalign.3 b/man3/posix_memalign.3 new file mode 100644 index 0000000..f0c1f6f --- /dev/null +++ b/man3/posix_memalign.3 @@ -0,0 +1,279 @@ +'\" t +.\" Copyright (c) 2001 by John Levon <moz@compsoc.man.ac.uk> +.\" Based in part on GNU libc documentation. +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2001-10-11, 2003-08-22, aeb, added some details +.\" 2012-03-23, Michael Kerrisk <mtk.manpages@mail.com> +.\" Document pvalloc() and aligned_alloc() +.TH posix_memalign 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +posix_memalign, aligned_alloc, memalign, valloc, pvalloc \- +allocate aligned memory +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdlib.h> +.PP +.BI "int posix_memalign(void **" memptr ", size_t " alignment ", size_t " size ); +.BI "void *aligned_alloc(size_t " alignment ", size_t " size ); +.BI "[[deprecated]] void *valloc(size_t " size ); +.PP +.B #include <malloc.h> +.PP +.BI "[[deprecated]] void *memalign(size_t " alignment ", size_t " size ); +.BI "[[deprecated]] void *pvalloc(size_t " size ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR posix_memalign (): +.nf + _POSIX_C_SOURCE >= 200112L +.fi +.PP +.BR aligned_alloc (): +.nf + _ISOC11_SOURCE +.fi +.PP +.BR valloc (): +.nf + Since glibc 2.12: + (_XOPEN_SOURCE >= 500) && !(_POSIX_C_SOURCE >= 200112L) + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _SVID_SOURCE || _BSD_SOURCE + Before glibc 2.12: + _BSD_SOURCE || _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED +.fi +.SH DESCRIPTION +The function +.BR posix_memalign () +allocates +.I size +bytes and places the address of the allocated memory in +.IR "*memptr" . +The address of the allocated memory will be a multiple of +.IR "alignment" , +which must be a power of two and a multiple of +.IR "sizeof(void\ *)" . +This address can later be successfully passed to +.BR free (3). +If +.I size +is 0, then +the value placed in +.I *memptr +is either NULL +.\" glibc does this: +or a unique pointer value. +.PP +The obsolete function +.BR memalign () +allocates +.I size +bytes and returns a pointer to the allocated memory. +The memory address will be a multiple of +.IR alignment , +which must be a power of two. +.\" The behavior of memalign() for size==0 is as for posix_memalign() +.\" but no standards govern this. +.PP +The function +.BR aligned_alloc () +is the same as +.BR memalign (), +except for the added restriction that +.I alignment +must be a power of two. +.PP +The obsolete function +.BR valloc () +allocates +.I size +bytes and returns a pointer to the allocated memory. +The memory address will be a multiple of the page size. +It is equivalent to +.IR "memalign(sysconf(_SC_PAGESIZE),size)" . +.PP +The obsolete function +.BR pvalloc () +is similar to +.BR valloc (), +but rounds the size of the allocation up to +the next multiple of the system page size. +.PP +For all of these functions, the memory is not zeroed. +.SH RETURN VALUE +.BR aligned_alloc (), +.BR memalign (), +.BR valloc (), +and +.BR pvalloc () +return a pointer to the allocated memory on success. +On error, NULL is returned, and \fIerrno\fP is set +to indicate the error. +.PP +.BR posix_memalign () +returns zero on success, or one of the error values listed in the +next section on failure. +The value of +.I errno +is not set. +On Linux (and other systems), +.BR posix_memalign () +does not modify +.I memptr +on failure. +A requirement standardizing this behavior was added in POSIX.1-2008 TC2. +.\" http://austingroupbugs.net/view.php?id=520 +.SH ERRORS +.TP +.B EINVAL +The +.I alignment +argument was not a power of two, or was not a multiple of +.IR "sizeof(void\ *)" . +.TP +.B ENOMEM +There was insufficient memory to fulfill the allocation request. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR aligned_alloc (), +.BR memalign (), +.BR posix_memalign () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR valloc (), +.BR pvalloc () +T} Thread safety MT-Unsafe init +.TE +.sp 1 +.SH STANDARDS +.TP +.BR aligned_alloc () +C11. +.TP +.BR posix_memalign () +POSIX.1-2008. +.TP +.BR memalign () +.TQ +.BR valloc () +None. +.TP +.BR pvalloc () +GNU. +.SH HISTORY +.TP +.BR aligned_alloc () +glibc 2.16. +C11. +.TP +.BR posix_memalign () +glibc 2.1.91. +POSIX.1d, POSIX.1-2001. +.TP +.BR memalign () +glibc 2.0. +SunOS 4.1.3. +.TP +.BR valloc () +glibc 2.0. +3.0BSD. +Documented as obsolete in 4.3BSD, +and as legacy in SUSv2. +.TP +.BR pvalloc () +glibc 2.0. +.\" +.SS Headers +Everybody agrees that +.BR posix_memalign () +is declared in \fI<stdlib.h>\fP. +.PP +On some systems +.BR memalign () +is declared in \fI<stdlib.h>\fP instead of \fI<malloc.h>\fP. +.PP +According to SUSv2, +.BR valloc () +is declared in \fI<stdlib.h>\fP. +.\" Libc4,5 and +glibc declares it in \fI<malloc.h>\fP, and also in +\fI<stdlib.h>\fP +if suitable feature test macros are defined (see above). +.SH NOTES +On many systems there are alignment restrictions, for example, on buffers +used for direct block device I/O. +POSIX specifies the +.I "pathconf(path,_PC_REC_XFER_ALIGN)" +call that tells what alignment is needed. +Now one can use +.BR posix_memalign () +to satisfy this requirement. +.PP +.BR posix_memalign () +verifies that +.I alignment +matches the requirements detailed above. +.BR memalign () +may not check that the +.I alignment +argument is correct. +.PP +POSIX requires that memory obtained from +.BR posix_memalign () +can be freed using +.BR free (3). +Some systems provide no way to reclaim memory allocated with +.BR memalign () +or +.BR valloc () +(because one can pass to +.BR free (3) +only a pointer obtained from +.BR malloc (3), +while, for example, +.BR memalign () +would call +.BR malloc (3) +and then align the obtained value). +.\" Other systems allow passing the result of +.\" .IR valloc () +.\" to +.\" .IR free (3), +.\" but not to +.\" .IR realloc (3). +The glibc implementation +allows memory obtained from any of these functions to be +reclaimed with +.BR free (3). +.PP +The glibc +.BR malloc (3) +always returns 8-byte aligned memory addresses, so these functions are +needed only if you require larger alignment values. +.SH SEE ALSO +.BR brk (2), +.BR getpagesize (2), +.BR free (3), +.BR malloc (3) |