Adding upstream version 6.05.01.upstream/6.05.01

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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)