MALLOCINFO(3) Linux Programmer's Manual MALLOCINFO(3)

NAME
       mallocinfo - export malloc state to a stream

SYNOPSIS
       #include 

       int mallocinfo(int options, FILE *fp);

DESCRIPTION
       The  mallocinfo()  function  exports  an XML string that describes the
       current state of the memory-allocation implementation  in  the  caller.
       The  string  is  printed  on  the  file stream fp.  The exported string
       includes information about all arenas (see malloc(3)).

       As currently implemented, options must be zero.

RETURN VALUE
       On success, mallocinfo() returns 0; on  error,  it  returns  -1,  with
       errno set to indicate the cause.

ERRORS
       EINVAL options was nonzero.

VERSIONS
       mallocinfo() was added to glibc in version 2.10.

CONFORMING TO
       This function is a GNU extension.

NOTES
       The  memory-allocation information is provided as an XML string (rather
       than a C structure)  because  the  information  may  change  over  time
       (according  to  changes  in the underlying implementation).  The output
       XML string includes a version field.

       The openmemstream(3) function can be used to send the output  of  mal‐
       locinfo() directly into a buffer in memory, rather than to a file.

       The  mallocinfo() function is designed to address deficiencies in mal‐
       locstats(3) and mallinfo(3).

EXAMPLE
       The program below takes up to four command-line arguments, of which the
       first  three are mandatory.  The first argument specifies the number of
       threads that the program should create.  All of the threads,  including
       the  main  thread, allocate the number of blocks of memory specified by
       the second argument.  The third  argument  controls  the  size  of  the
       blocks  to  be allocated.  The main thread creates blocks of this size,
       the second thread created by the program allocates blocks of twice this
       size,  the  third thread allocates blocks of three times this size, and
       so on.

       The program calls mallocinfo() twice to display the  memory-allocation
       state.   The  first  call takes place before any threads are created or
       memory allocated.  The second call is performed after all threads  have
       allocated memory.

       In  the  following example, the command-line arguments specify the cre‐
       ation of one additional thread, and both the main thread and the  addi‐
       tional  thread  allocate  10000  blocks of memory.  After the blocks of
       memory have been allocated, mallocinfo() shows the state of two  allo‐
       cation arenas.

           $ getconf GNULIBCVERSION
           glibc 2.13
           $ ./a.out 1 10000 100
           ============ Before allocating blocks ============
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           

           ============ After allocating blocks ============
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           
           

   Program source
       #include 
       #include 
       #include 
       #include 
       #include 

       static sizet blockSize;
       static int numThreads, numBlocks;

       #define errExit(msg)    do { perror(msg); exit(EXITFAILURE); \
                               } while (0)

       static void *
       threadfunc(void *arg)
       {
           int j;
           int tn = (int) arg;

           /* The multiplier '(2 + tn)' ensures that each thread (including
              the main thread) allocates a different amount of memory */

           for (j = 0; j < numBlocks; j++)
               if (malloc(blockSize * (2 + tn)) == NULL)
                   errExit("malloc-thread");

           sleep(100);         /* Sleep until main thread terminates */
           return NULL;
       }

       int
       main(int argc, char *argv[])
       {
           int j, tn, sleepTime;
           pthreadt *thr;

           if (argc < 4) {
               fprintf(stderr,
                       "%s num-threads num-blocks block-size [sleep-time]\n",
                       argv[0]);
               exit(EXITFAILURE);
           }

           numThreads = atoi(argv[1]);
           numBlocks = atoi(argv[2]);
           blockSize = atoi(argv[3]);
           sleepTime = (argc > 4) ? atoi(argv[4]) : 0;

           thr = calloc(numThreads, sizeof(pthreadt));
           if (thr == NULL)
               errExit("calloc");

           printf("============ Before allocating blocks ============\n");
           mallocinfo(0, stdout);

           /* Create threads that allocate different amounts of memory */

           for (tn = 0; tn < numThreads; tn++) {
               errno = pthreadcreate(&thr[tn], NULL, threadfunc,
                                      (void *) tn);
               if (errno != 0)
                   errExit("pthreadcreate");

               /* If we add a sleep interval after the start-up of each
                  thread, the threads likely won't contend for malloc
                  mutexes, and therefore additional arenas won't be
                  allocated (see malloc(3)). */

               if (sleepTime > 0)
                   sleep(sleepTime);
           }

           /* The main thread also allocates some memory */

           for (j = 0; j < numBlocks; j++)
               if (malloc(blockSize) == NULL)
                   errExit("malloc");

           sleep(2);           /* Give all threads a chance to
                                  complete allocations */

           printf("\n============ After allocating blocks ============\n");
           mallocinfo(0, stdout);

           exit(EXITSUCCESS);
       }

SEE ALSO
       mallinfo(3), malloc(3), mallocstats(3), mallopt(3), openmemstream(3)

COLOPHON
       This  page  is  part of release 3.53 of the Linux man-pages project.  A
       description of the project, and information about reporting  bugs,  can
       be found at http://www.kernel.org/doc/man-pages/.



GNU                               2013-04-19                    MALLOCINFO(3)