draft/man3/malloc_info.3

   1 .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\"*******************************************************************
  26 .\"
  27 .\" This file was generated with po4a. Translate the source file.
  28 .\"
  29 .\"*******************************************************************
  30 .TH MALLOC_INFO 3 2013\-04\-19 GNU "Linux Programmer's Manual"
  31 .SH 名前
  32 malloc_info \- export malloc state to a stream
  33 .SH 書式
  34 .nf
  35 \fB#include <malloc.h>\fP
  36 .sp
  37 \fBint malloc_info(int \fP\fIoptions\fP\fB, FILE *\fP\fIfp\fP\fB);\fP
  38 .fi
  39 .SH 説明
  40 The \fBmalloc_info\fP()  function exports an XML string that describes the
  41 current state of the memory\-allocation implementation in the caller.  The
  42 string is printed on the file stream \fIfp\fP.  The exported string includes
  43 information about all arenas (see \fBmalloc\fP(3)).
  44
  45 As currently implemented, \fIoptions\fP must be zero.
  46 .SH 返り値
  47 \fBmalloc_info\fP() は、成功すると 0 を返す。 エラーの場合、\-1 を返し、 \fIerrno\fP にエラーの原因を示す値を設定する。
  48 .SH エラー
  49 .TP
  50 \fBEINVAL\fP
  51 \fIoptions\fP was nonzero.
  52 .SH バージョン
  53 \fBmalloc_info\fP() は glibc バージョン 2.10 で追加された。
  54 .SH 準拠
  55 この関数は GNU による拡張である。
  56 .SH 注意
  57 The memory\-allocation information is provided as an XML string (rather than
  58 a C structure)  because the information may change over time (according to
  59 changes in the underlying implementation).  The output XML string includes a
  60 version field.
  61
  62 The \fBopen_memstream\fP(3)  function can be used to send the output of
  63 \fBmalloc_info\fP()  directly into a buffer in memory, rather than to a file.
  64
  65 The \fBmalloc_info\fP()  function is designed to address deficiencies in
  66 \fBmalloc_stats\fP(3)  and \fBmallinfo\fP(3).
  67 .SH 例
  68 The program below takes up to four command\-line arguments, of which the
  69 first three are mandatory.  The first argument specifies the number of
  70 threads that the program should create.  All of the threads, including the
  71 main thread, allocate the number of blocks of memory specified by the second
  72 argument.  The third argument controls the size of the blocks to be
  73 allocated.  The main thread creates blocks of this size, the second thread
  74 created by the program allocates blocks of twice this size, the third thread
  75 allocates blocks of three times this size, and so on.
  76
  77 The program calls \fBmalloc_info\fP()  twice to display the memory\-allocation
  78 state.  The first call takes place before any threads are created or memory
  79 allocated.  The second call is performed after all threads have allocated
  80 memory.
  81
  82 In the following example, the command\-line arguments specify the creation of
  83 one additional thread, and both the main thread and the additional thread
  84 allocate 10000 blocks of memory.  After the blocks of memory have been
  85 allocated, \fBmalloc_info\fP()  shows the state of two allocation arenas.
  86 .in +4
  87 .nf
  88
  89 $ \fBgetconf GNU_LIBC_VERSION\fP
  90 glibc 2.13
  91 $ \fB./a.out 1 10000 100\fP
  92 ============ Before allocating blocks ============
  93 <malloc version="1">
  94 <heap nr="0">
  95 <sizes>
  96 </sizes>
  97 <total type="fast" count="0" size="0"/>
  98 <total type="rest" count="0" size="0"/>
  99 <system type="current" size="135168"/>
 100 <system type="max" size="135168"/>
 101 <aspace type="total" size="135168"/>
 102 <aspace type="mprotect" size="135168"/>
 103 </heap>
 104 <total type="fast" count="0" size="0"/>
 105 <total type="rest" count="0" size="0"/>
 106 <system type="current" size="135168"/>
 107 <system type="max" size="135168"/>
 108 <aspace type="total" size="135168"/>
 109 <aspace type="mprotect" size="135168"/>
 110 </malloc>
 111
 112 ============ After allocating blocks ============
 113 <malloc version="1">
 114 <heap nr="0">
 115 <sizes>
 116 </sizes>
 117 <total type="fast" count="0" size="0"/>
 118 <total type="rest" count="0" size="0"/>
 119 <system type="current" size="1081344"/>
 120 <system type="max" size="1081344"/>
 121 <aspace type="total" size="1081344"/>
 122 <aspace type="mprotect" size="1081344"/>
 123 </heap>
 124 <heap nr="1">
 125 <sizes>
 126 </sizes>
 127 <total type="fast" count="0" size="0"/>
 128 <total type="rest" count="0" size="0"/>
 129 <system type="current" size="1032192"/>
 130 <system type="max" size="1032192"/>
 131 <aspace type="total" size="1032192"/>
 132 <aspace type="mprotect" size="1032192"/>
 133 </heap>
 134 <total type="fast" count="0" size="0"/>
 135 <total type="rest" count="0" size="0"/>
 136 <system type="current" size="2113536"/>
 137 <system type="max" size="2113536"/>
 138 <aspace type="total" size="2113536"/>
 139 <aspace type="mprotect" size="2113536"/>
 140 </malloc>
 141 .fi
 142 .in
 143 .SS プログラムのソース
 144 .nf
 145
 146 #include <unistd.h>
 147 #include <stdlib.h>
 148 #include <pthread.h>
 149 #include <malloc.h>
 150 #include <errno.h>
 151
 152 static size_t blockSize;
 153 static int numThreads, numBlocks;
 154
 155 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 156                         } while (0)
 157
 158 static void *
 159 thread_func(void *arg)
 160 {
 161     int j;
 162     int tn = (int) arg;
 163
 164     /* The multiplier \(aq(2 + tn)\(aq ensures that each thread (including
 165        the main thread) allocates a different amount of memory */
 166
 167     for (j = 0; j < numBlocks; j++)
 168         if (malloc(blockSize * (2 + tn)) == NULL)
 169             errExit("malloc\-thread");
 170
 171     sleep(100);         /* Sleep until main thread terminates */
 172     return NULL;
 173 }
 174
 175 int
 176 main(int argc, char *argv[])
 177 {
 178     int j, tn, sleepTime;
 179     pthread_t *thr;
 180
 181     if (argc < 4) {
 182         fprintf(stderr,
 183                 "%s num\-threads num\-blocks block\-size [sleep\-time]\en",
 184                 argv[0]);
 185         exit(EXIT_FAILURE);
 186     }
 187
 188     numThreads = atoi(argv[1]);
 189     numBlocks = atoi(argv[2]);
 190     blockSize = atoi(argv[3]);
 191     sleepTime = (argc > 4) ? atoi(argv[4]) : 0;
 192
 193     thr = calloc(numThreads, sizeof(pthread_t));
 194     if (thr == NULL)
 195         errExit("calloc");
 196
 197     printf("============ Before allocating blocks ============\en");
 198     malloc_info(0, stdout);
 199
 200     /* Create threads that allocate different amounts of memory */
 201
 202     for (tn = 0; tn < numThreads; tn++) {
 203         errno = pthread_create(&thr[tn], NULL, thread_func,
 204                                (void *) tn);
 205         if (errno != 0)
 206             errExit("pthread_create");
 207
 208         /* If we add a sleep interval after the start\-up of each
 209            thread, the threads likely won\(aqt contend for malloc
 210            mutexes, and therefore additional arenas won\(aqt be
 211            allocated (see malloc(3)). */
 212
 213         if (sleepTime > 0)
 214             sleep(sleepTime);
 215     }
 216
 217     /* The main thread also allocates some memory */
 218
 219     for (j = 0; j < numBlocks; j++)
 220         if (malloc(blockSize) == NULL)
 221             errExit("malloc");
 222
 223     sleep(2);           /* Give all threads a chance to
 224                            complete allocations */
 225
 226     printf("\en============ After allocating blocks ============\en");
 227     malloc_info(0, stdout);
 228
 229     exit(EXIT_SUCCESS);
 230 }
 231 .fi
 232 .SH 関連項目
 233 \fBmallinfo\fP(3), \fBmalloc\fP(3), \fBmalloc_stats\fP(3), \fBmallopt\fP(3),
 234 \fBopen_memstream\fP(3)
 235 .SH この文書について
 236 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.52 の一部
 237 である。プロジェクトの説明とバグ報告に関する情報は
 238 http://www.kernel.org/doc/man\-pages/ に書かれている。