.TH LIBSIMPLE_ALIGNED_WMEMDUP 3 libsimple
.SH NAME
libsimple_aligned_wmemdup, libsimple_aligned_wmemdupa \- duplicate a wide-character array

.SH SYNOPSIS
.nf
#include <libsimple.h>

wchar_t *libsimple_aligned_wmemdupa(const wchar_t *\fIs\fP, size_t \fIalignment\fP, size_t \fIn\fP);
wchar_t *libsimple_aligned_wmemdup(const wchar_t *\fIs\fP, size_t \fIalignment\fP, size_t \fIn\fP);
wchar_t *libsimple_enaligned_wmemdup(int \fIstatus\fP, const wchar_t *\fIs\fP, size_t \fIalignment\fP, size_t \fIn\fP);
inline wchar_t *libsimple_ealigned_wmemdup(const wchar_t *\fIs\fP, size_t \fIalignment\fP, size_t \fIn\fP);

#ifndef aligned_wmemdupa
# define aligned_wmemdupa libsimple_aligned_wmemdupa
#endif
#ifndef aligned_wmemdup
# define aligned_wmemdup libsimple_aligned_wmemdup
#endif
#ifndef enaligned_wmemdup
# define enaligned_wmemdup libsimple_enaligned_wmemdup
#endif
#ifndef ealigned_wmemdup
# define ealigned_wmemdup libsimple_ealigned_wmemdup
#endif
.fi
.PP
Link with
.IR \-lsimple .

.SH DESCRIPTION
The
.BR libsimple_aligned_wmemdup ()
function allocates memory with the alignment
specified in the
.I alignment
parameter and copies
.I n
first wide characters
.RB ( wchar_t )
from
.I s
into the new allocation.
.PP
The
.BR libsimple_enaligned_wmemdup ()
and
.BR libsimple_ealigned_wmemdup ()
functions are versions of the
.BR libsimple_aligned_wmemdup ()
function that call the
.BR libsimple_enprintf (3)
function on failure, causing the process to print
an error message and exit. See
.BR libsimple_enprintf (3)
for more information.
.PP
The
.BR libsimple_wmemdupa ()
function is implemented as a macro and is a version
of the
.BR libsimple_wmemdup ()
function that uses allocates the memory on the stack
rather than on the heap, causing the return pointer
to become invalid when the calling function returns.
It is only available when compling with GCC or Clang.

.SH RETURN VALUE
Upon successful completion, the
.BR libsimple_aligned_wmemdupa (),
.BR libsimple_aligned_wmemdup (),
.BR libsimple_enaligned_wmemdup (),
and
.BR libsimple_ealigned_wmemdup ()
functions return a non-null pointer, on failure the
.BR libsimple_aligned_wmemdup ()
function returns
.B NULL
and set
.I errno
to indicate the error, and the
.BR libsimple_enaligned_wmemdup (),
and
.BR libsimple_ealigned_wmemdup ()
functions exit the process. The
.BR libsimple_aligned_wmemdupa ()
function cannot fail, however the kernel
can kill the thread, and possibly the process, with a
.B SIGSEGV
signal if the memory cannot be allocated.
.PP
The returned pointer should be deallocated when it
is no longer needed, except for the pointer returned
by the
.BR libsimple_aligned_wmemdupa ()
function, it is automatically deallocated when the
calling function returns.

.SH ERRORS
The
.BR libsimple_aligned_wmemdup ()
function may fail for any reason specified for the
.BR aligned_alloc (3)
function.

.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lb lb lb
l l l.
Interface	Attribute	Value
T{
.BR libsimple_aligned_wmemdupa (),
.br
.BR libsimple_aligned_wmemdup (),
.br
.BR libsimple_enaligned_wmemdup (),
.br
.BR libsimple_ealigned_wmemdup (),
T}	Thread safety	MT-Safe
T{
.BR libsimple_aligned_wmemdupa (),
.br
.BR libsimple_aligned_wmemdup (),
.br
.BR libsimple_enaligned_wmemdup (),
.br
.BR libsimple_ealigned_wmemdup (),
T}	Async-signal safety	AS-Safe
T{
.BR libsimple_aligned_wmemdupa (),
.br
.BR libsimple_aligned_wmemdup (),
.br
.BR libsimple_enaligned_wmemdup (),
.br
.BR libsimple_ealigned_wmemdup (),
T}	Async-cancel safety	AC-Safe
.TE

.SH EXAMPLES
None.

.SH APPLICATION USAGE
None.

.SH RATIONALE
None.

.SH FUTURE DIRECTIONS
None.

.SH NOTES
None.

.SH HISTORY
libsimple 1.2

.SH BUGS
None.

.SH SEE ALSO
.BR libsimple_wmemdup (3),
.BR libsimple_aligned_strndup (3),
.BR libsimple_aligned_strdup (3),
.BR libsimple_aligned_memdup (3),
.BR libsimple_aligned_wcsdup (3),
.BR libsimple_aligned_wcsndup (3)