gitweb.dragonflybsd.org Git - dragonfly.git/blame_incremental

... / ...

Commit	Line	Data
	1	.\" Copyright (C) 2006 Jason Evans <jasone@FreeBSD.org>.
	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice(s), this list of conditions and the following disclaimer as
	9	.\" the first lines of this file unmodified other than the possible
	10	.\" addition of one or more copyright notices.
	11	.\" 2. Redistributions in binary form must reproduce the above copyright
	12	.\" notice(s), this list of conditions and the following disclaimer in
	13	.\" the documentation and/or other materials provided with the
	14	.\" distribution.
	15	.\"
	16	.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
	17	.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	18	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
	19	.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
	20	.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	21	.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	22	.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
	23	.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
	24	.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
	25	.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
	26	.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	27	.\"
	28	.Dd August 9, 2012
	29	.Dt POSIX_MEMALIGN 3
	30	.Os
	31	.Sh NAME
	32	.Nm posix_memalign ,
	33	.Nm aligned_alloc
	34	.Nd aligned memory allocation
	35	.Sh LIBRARY
	36	.Lb libc
	37	.Sh SYNOPSIS
	38	.In stdlib.h
	39	.Ft int
	40	.Fn posix_memalign "void **ptr" "size_t alignment" "size_t size"
	41	.Ft void *
	42	.Fn aligned_alloc "size_t alignment" "size_t size"
	43	.Sh DESCRIPTION
	44	The
	45	.Fn posix_memalign
	46	function allocates
	47	.Fa size
	48	bytes of memory such that the allocation's base address is an even multiple of
	49	.Fa alignment ,
	50	and returns the allocation in the value pointed to by
	51	.Fa ptr .
	52	.Pp
	53	The requested
	54	.Fa alignment
	55	must be a power of 2 at least as large as
	56	.Fn sizeof "void *" .
	57	.Pp
	58	Memory that is allocated via
	59	.Fn posix_memalign
	60	can be used as an argument in subsequent calls to
	61	.Xr realloc 3 ,
	62	.Xr reallocf 3 ,
	63	and
	64	.Xr free 3 .
	65	.Pp
	66	The
	67	.Fn aligned_alloc
	68	function is the same as
	69	.Fn posix_memalign ,
	70	but it takes just
	71	.Fa alignment
	72	and
	73	.Fa size
	74	and the allocation pointer is returned.
	75	.Sh IMPLEMENTATION NOTES
	76	The
	77	.Fn posix_memalign
	78	function is directly supported by matching the requested alignment against a zone
	79	of the slab allocator with a compatible chunking, and using the power-of-2
	80	shortcut whenever possible.
	81	Alignments beyond those supported by the zone mechanism are still
	82	guaranteed using cute
	83	.Xr mmap 2
	84	tricks.
	85	Our
	86	.Fn posix_memalign
	87	is thus able to take advantage of the slab allocator to produce
	88	well-fitted results when the requests are reasonable.
	89	.Sh RETURN VALUES
	90	The
	91	.Fn posix_memalign
	92	function returns the value 0 if successful; otherwise it returns an error value.
	93	The
	94	.Fn aligned_alloc
	95	returns a pointer to the allocated memory if successful; otherwise a
	96	.Dv NULL
	97	pointer is returned and
	98	.Va errno
	99	is set.
	100	.Sh ERRORS
	101	The
	102	.Fn posix_memalign
	103	and
	104	.Fn aligned_alloc
	105	functions will fail if:
	106	.Bl -tag -width Er
	107	.It Bq Er EINVAL
	108	The
	109	.Fa alignment
	110	parameter is not a power of 2 at least as large as
	111	.Fn sizeof "void *" .
	112	.It Bq Er ENOMEM
	113	Memory allocation error.
	114	.El
	115	.Sh SEE ALSO
	116	.Xr free 3 ,
	117	.Xr malloc 3 ,
	118	.Xr realloc 3 ,
	119	.Xr reallocf 3 ,
	120	.Xr valloc 3
	121	.Sh STANDARDS
	122	The
	123	.Fn posix_memalign
	124	function conforms to
	125	.St -p1003.1-2008 .
	126	The
	127	.Fn aligned_alloc
	128	function conforms to
	129	.St -isoC-2011 .