RTEMS 4.9.5 On-Line Library

Memory Commands malloc - obtain information on C program heap

RTEMS Shell User's Guide

4.2.6: malloc - obtain information on C program heap

SYNOPSYS:

malloc [info|stats]

DESCRIPTION:

This command prints either information or statistics about the C Program Heap used by the malloc family of calls based upon the value of the first argument passed to the command.

When the subcommand info is specified, information on the current state of the C Program Heap is reported. This includes the following information:

Number of free blocks
Largest free block
Total bytes free
Number of used blocks
Largest used block
Total bytes used

When the subcommand stats is specified, statistics on the the C Program Heap are reported. Malloc Family Statistics must be enabled for all of the values to be updated. The statistics available includes the following information:

Currently available memory (in kilobytes)
Currently allocated memory (in kilobytes)
Maximum amount of memory ever allocated (in kilobytes)
Lifetime tally of allocated memory (in kilobytes)
Lifetime tally of freed memory (in kilobytes)
Number of calls to malloc
Number of calls to free
Number of calls to realloc
Number of calls to calloc

EXIT STATUS:

This command returns 0 on success and non-zero if an error is encountered.

NOTES:

The CONFIGURE_MALLOC_STATISTICS confdefs.h constant must be defined when the application is configured for the full set of statistics information to be available.

EXAMPLES:

The following is an example of how to use the malloc command.

SHLL [/] $ malloc info
Number of free blocks: 3
Largest free block:    3626672
Total bytes free:      3627768
Number of used blocks: 130
Largest used block:    1048
Total bytes used:      10136
SHLL [/] $ malloc stats
Malloc statistics
  avail:3552k  allocated:9k (0%) max:10k (0%) lifetime:21k freed:12k
  Call counts:   malloc:203   free:93   realloc:0   calloc:20
SHLL [/] $ malloc info
Number of free blocks: 3
Largest free block:    3626672
Total bytes free:      3627768
Number of used blocks: 130
Largest used block:    1048
Total bytes used:      10136
SHLL [/] $ malloc stats
Malloc statistics
  avail:3552k  allocated:9k (0%) max:10k (0%) lifetime:23k freed:14k
  Call counts:   malloc:205   free:95   realloc:0   calloc:20

Note that in the above example, the lifetime allocated and free values have increased between the two calls to malloc stats even though the amount of memory available in the C Program Heap is the same in both the malloc info invocations. This indicates that memory was allocated and freed as a side-effect of the commands.

CONFIGURATION:

This command is included in the default shell command set. When building a custom command set, define CONFIGURE_SHELL_COMMAND_MALLOC to have this command included.

This command can be excluded from the shell command set by defining CONFIGURE_SHELL_NO_COMMAND_MALLOC when all shell commands have been configured.

PROGRAMMING INFORMATION:

The malloc is implemented by a C language function which has the following prototype:

int rtems_shell_rtems_main_malloc(
  int    argc,
  char **argv
);

The configuration structure for the malloc has the following prototype:

extern rtems_shell_cmd_t rtems_shell_MALLOC_Command;

RTEMS Shell User's Guide