From patchwork Wed Nov 6 10:06:41 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Will Newton X-Patchwork-Id: 21363 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-ie0-f197.google.com (mail-ie0-f197.google.com [209.85.223.197]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id EE85720DB9 for ; Wed, 6 Nov 2013 10:06:45 +0000 (UTC) Received: by mail-ie0-f197.google.com with SMTP id e14sf29438223iej.0 for ; Wed, 06 Nov 2013 02:06:45 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:delivered-to:message-id:date:from:user-agent :mime-version:to:cc:subject:x-original-sender :x-original-authentication-results:precedence:mailing-list:list-id :list-post:list-help:list-archive:list-unsubscribe:content-type :content-transfer-encoding; bh=vo4WxabVb1C3dShnxSHdzUr2hhvHDajwO+9aWu2dXVY=; b=K7dp8vCgY98lH3E3TqXSbgTJzVz33pA9NVcNkSqviEXYTUsHhEYwmWr/tkoN1I07Va bnRnULZKMPF7UxtWyiL/DezwSpJZRi6sAOfDNeXwpeRqOsgAfjj5STrz+BzAYticAdsE Ab0ULjLmV1AibWooso4k26VYnppIKMohJwY0NFF6PL5xS61/Hm9M/x69cA/1Xu39fi3J T40ua+Vip5FlmmhGxk5dsYSAu/56vcJ2GuygdGgfMesxW+vD7qoO76PKiyOb32m7HbbP ZNqwwhfT/ZNHQGcBdOG7MxCej0/++cpqOJEMOj3XzF6edwKrq5q6Cycqn/I4RrmcPMUK 5ftw== X-Gm-Message-State: ALoCoQnMOkGgVKBgfEXuBBwUcDYL1rqn+r0kvIoVt67MCn8taNwpXrlX9KuHzjI8l39nnAAamBcy X-Received: by 10.182.48.195 with SMTP id o3mr786107obn.22.1383732405563; Wed, 06 Nov 2013 02:06:45 -0800 (PST) X-BeenThere: patchwork-forward@linaro.org Received: by 10.49.133.73 with SMTP id pa9ls643618qeb.70.gmail; Wed, 06 Nov 2013 02:06:45 -0800 (PST) X-Received: by 10.58.168.205 with SMTP id zy13mr1682434veb.19.1383732405445; Wed, 06 Nov 2013 02:06:45 -0800 (PST) Received: from mail-ve0-f175.google.com (mail-ve0-f175.google.com [209.85.128.175]) by mx.google.com with ESMTPS id hs8si6826432veb.60.2013.11.06.02.06.45 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 06 Nov 2013 02:06:45 -0800 (PST) Received-SPF: neutral (google.com: 209.85.128.175 is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) client-ip=209.85.128.175; Received: by mail-ve0-f175.google.com with SMTP id jz11so3375190veb.20 for ; Wed, 06 Nov 2013 02:06:45 -0800 (PST) X-Received: by 10.220.74.69 with SMTP id t5mr1720588vcj.18.1383732405368; Wed, 06 Nov 2013 02:06:45 -0800 (PST) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patches@linaro.org Received: by 10.220.174.196 with SMTP id u4csp272645vcz; Wed, 6 Nov 2013 02:06:44 -0800 (PST) X-Received: by 10.204.197.136 with SMTP id ek8mr78005bkb.65.1383732404322; Wed, 06 Nov 2013 02:06:44 -0800 (PST) Received: from mail-bk0-f44.google.com (mail-bk0-f44.google.com [209.85.214.44]) by mx.google.com with ESMTPS id uo6si4107911bkb.344.2013.11.06.02.06.43 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 06 Nov 2013 02:06:44 -0800 (PST) Received-SPF: neutral (google.com: 209.85.214.44 is neither permitted nor denied by best guess record for domain of will.newton@linaro.org) client-ip=209.85.214.44; Received: by mail-bk0-f44.google.com with SMTP id mx11so1394751bkb.31 for ; Wed, 06 Nov 2013 02:06:43 -0800 (PST) X-Received: by 10.204.197.136 with SMTP id ek8mr77972bkb.65.1383732403692; Wed, 06 Nov 2013 02:06:43 -0800 (PST) Received: from localhost.localdomain (cpc6-seac21-2-0-cust453.7-2.cable.virginm.net. [82.1.113.198]) by mx.google.com with ESMTPSA id qg7sm22490617bkb.6.2013.11.06.02.06.42 for (version=TLSv1 cipher=RC4-SHA bits=128/128); Wed, 06 Nov 2013 02:06:42 -0800 (PST) Message-ID: <527A14B1.5080903@linaro.org> Date: Wed, 06 Nov 2013 10:06:41 +0000 From: Will Newton User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130805 Thunderbird/17.0.8 MIME-Version: 1.0 To: libc-alpha@sourceware.org CC: Patch Tracking Subject: [PATCH 2/2] manual/memory.texi: Bring aligned allocation docs up to date. X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: will.newton@linaro.org X-Original-Authentication-Results: mx.google.com; spf=neutral (google.com: 209.85.128.175 is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Precedence: list Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org List-ID: X-Google-Group-Id: 836684582541 List-Post: , List-Help: , List-Archive: List-Unsubscribe: , The current documentation suggests using memalign and valloc which are now considered obsolete, so suggest using posix_memalign instead. Also document the possible error return and errno values for memalign and posix_memalign and improve documentation of __memalign_hook. ChangeLog: 2013-11-06 Will Newton * manual/memory.texi (Malloc Examples): Clarify default alignment documentation. Suggest posix_memalign rather than memalign or valloc. (Aligned Memory Blocks): Remove suggestion to use memalign or valloc. Remove obsolete comment about BSD. Document memalign errno values and mark the function obsolete. Document posix_memalign returned error codes. Mark valloc as obsolete. (Hooks for Malloc): __memalign_hook is also called for posix_memalign and valloc. (Summary of Malloc): Add posix_memalign to function summary. __memalign_hook is also called for posix_memalign and valloc. --- manual/memory.texi | 61 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 44 insertions(+), 17 deletions(-) diff --git a/manual/memory.texi b/manual/memory.texi index a80f87c..c36ea12 100644 --- a/manual/memory.texi +++ b/manual/memory.texi @@ -380,10 +380,10 @@ savestring (const char *ptr, size_t len) The block that @code{malloc} gives you is guaranteed to be aligned so that it can hold any type of data. On @gnusystems{}, the address is -always a multiple of eight on most systems, and a multiple of 16 on +always a multiple of eight on 32-bit systems, and a multiple of 16 on 64-bit systems. Only rarely is any higher boundary (such as a page -boundary) necessary; for those cases, use @code{memalign}, -@code{posix_memalign} or @code{valloc} (@pxref{Aligned Memory Blocks}). +boundary) necessary; for those cases, use @code{posix_memalign} +(@pxref{Aligned Memory Blocks}). Note that the memory located after the end of the block is likely to be in use for something else; perhaps a block already allocated by another @@ -616,14 +616,8 @@ after calling @code{free} wastes memory. The size threshold for The address of a block returned by @code{malloc} or @code{realloc} in @gnusystems{} is always a multiple of eight (or sixteen on 64-bit systems). If you need a block whose address is a multiple of a higher -power of two than that, use @code{memalign}, @code{posix_memalign}, or -@code{valloc}. @code{memalign} is declared in @file{malloc.h} and -@code{posix_memalign} is declared in @file{stdlib.h}. - -With @theglibc{}, you can use @code{free} to free the blocks that -@code{memalign}, @code{posix_memalign}, and @code{valloc} return. That -does not work in BSD, however---BSD does not provide any way to free -such blocks. +power of two than that, use @code{posix_memalign}. @code{posix_memalign} +is declared in @file{stdlib.h}. @comment malloc.h @comment BSD @@ -633,6 +627,21 @@ address is a multiple of @var{boundary}. The @var{boundary} must be a power of two! The function @code{memalign} works by allocating a somewhat larger block, and then returning an address within the block that is on the specified boundary. + +The @code{memalign} function returns a null pointer on error and sets +@code{errno} to one of the following values: + +@table @code +@item ENOMEM +@var{alignment} is not a power of two. + +@item EINVAL +There was insufficient memory available to satisfy the request. + +@end table + +The @code{memalign} function is obsolete and @code{posix_memalign} should +be used instead. @end deftypefun @comment stdlib.h @@ -647,6 +656,16 @@ parameter @var{alignment}: the value must be a power of two multiple of If the function succeeds in allocation memory a pointer to the allocated memory is returned in @code{*@var{memptr}} and the return value is zero. Otherwise the function returns an error value indicating the problem. +The possible error values returned are: + +@table @code +@item ENOMEM +@var{alignment} is not a power of two multiple of @code{sizeof (void *)}. + +@item EINVAL +There was insufficient memory available to satisfy the request. + +@end table This function was introduced in POSIX 1003.1d. @end deftypefun @@ -667,6 +686,9 @@ valloc (size_t size) @ref{Query Memory Parameters} for more information about the memory subsystem. + +The @code{valloc} function is obsolete and @code{posix_memalign} should +be used instead. @end deftypefun @node Malloc Tunable Parameters @@ -902,17 +924,17 @@ memory consumption of the program. @comment malloc.h @comment GNU @defvar __memalign_hook -The value of this variable is a pointer to function that @code{memalign} -uses whenever it is called. You should define this function to look -like @code{memalign}; that is, like: +The value of this variable is a pointer to function that @code{memalign}, +@code{posix_memalign} and @code{valloc} use whenever they are called. +You should define this function to look like @code{memalign}; that is, like: @smallexample void *@var{function} (size_t @var{alignment}, size_t @var{size}, const void *@var{caller}) @end smallexample The value of @var{caller} is the return address found on the stack when -the @code{memalign} function was called. This value allows you to trace the -memory consumption of the program. +the @code{memalign}, @code{posix_memalign} or @code{valloc} functions are +called. This value allows you to trace the memory consumption of the program. @end defvar You must make sure that the function you install as a hook for one of @@ -1118,6 +1140,10 @@ Space}. Allocate a block of @var{size} bytes, starting on a page boundary. @xref{Aligned Memory Blocks}. +@item int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size}) +Allocate a block of @var{size} bytes, starting on an address that is a +multiple of @var{alignment}. @xref{Aligned Memory Blocks}. + @item void *memalign (size_t @var{size}, size_t @var{boundary}) Allocate a block of @var{size} bytes, starting on an address that is a multiple of @var{boundary}. @xref{Aligned Memory Blocks}. @@ -1140,7 +1166,8 @@ A pointer to a function that @code{realloc} uses whenever it is called. A pointer to a function that @code{free} uses whenever it is called. @item void (*__memalign_hook) (size_t @var{size}, size_t @var{alignment}, const void *@var{caller}) -A pointer to a function that @code{memalign} uses whenever it is called. +A pointer to a function that @code{memalign}, @code{posix_memalign} and +@code{valloc} use whenever they are called. @item struct mallinfo mallinfo (void) Return information about the current dynamic memory usage.