man3/malloc_trim.3

   1 '\" t
   2 .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH malloc_trim 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 malloc_trim \- release free memory from the heap
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <malloc.h>
  15 .PP
  16 .BI "int malloc_trim(size_t "  pad );
  17 .fi
  18 .SH DESCRIPTION
  19 The
  20 .BR malloc_trim ()
  21 function attempts to release free memory from the heap
  22 (by calling
  23 .BR sbrk (2)
  24 or
  25 .BR madvise (2)
  26 with suitable arguments).
  27 .PP
  28 The
  29 .I pad
  30 argument specifies the amount of free space to leave untrimmed
  31 at the top of the heap.
  32 If this argument is 0, only the minimum amount of memory is maintained
  33 at the top of the heap (i.e., one page or less).
  34 A nonzero argument can be used to maintain some trailing space
  35 at the top of the heap in order to allow future allocations
  36 to be made without having to extend the heap with
  37 .BR sbrk (2).
  38 .SH RETURN VALUE
  39 The
  40 .BR malloc_trim ()
  41 function returns 1 if memory was actually released back to the system,
  42 or 0 if it was not possible to release any memory.
  43 .SH ERRORS
  44 No errors are defined.
  45 .\" .SH VERSIONS
  46 .\" Available already in glibc 2.0, possibly earlier
  47 .SH ATTRIBUTES
  48 For an explanation of the terms used in this section, see
  49 .BR attributes (7).
  50 .ad l
  51 .nh
  52 .TS
  53 allbox;
  54 lbx lb lb
  55 l l l.
  56 Interface       Attribute       Value
  57 T{
  58 .BR malloc_trim ()
  59 T}      Thread safety   MT-Safe
  60 .TE
  61 .hy
  62 .ad
  63 .sp 1
  64 .SH STANDARDS
  65 This function is a GNU extension.
  66 .SH NOTES
  67 Only the main heap (using
  68 .BR sbrk (2))
  69 honors the
  70 .I pad
  71 argument; thread heaps do not.
  72 .PP
  73 Since glibc 2.8 this function frees memory in all arenas and in all
  74 chunks with whole free pages.
  75 .\" See commit 68631c8eb92ff38d9da1ae34f6aa048539b199cc
  76 .\" (dated 2007-12-16) which adds iteration over all
  77 .\" arenas and frees all pages in chunks which are free.
  78 .PP
  79 Before glibc 2.8 this function only freed memory at the
  80 top of the heap in the main arena.
  81 .SH SEE ALSO
  82 .BR sbrk (2),
  83 .BR malloc (3),
  84 .BR mallopt (3)