man3/malloc_trim.3

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