Dogcows Code - chaz/p5-Linux-Proc-Maps/blob - README

   1 NAME
   2
   3     Linux::Proc::Maps - Read and write /proc/[pid]/maps files
   4
   5 VERSION
   6
   7     version 0.001
   8
   9 SYNOPSIS
  10
  11         use Linux::Proc::Maps qw(read_maps);
  12
  13         # by pid:
  14         my $vm_regions = read_maps(pid => $$);
  15
  16         # by pid with explicit procfs mount:
  17         my $vm_regions = read_maps(mnt => '/proc', pid => 123);
  18
  19         # by file:
  20         my $vm_regions = read_maps(file => '/proc/456/maps');
  21
  22 DESCRIPTION
  23
  24     This module reads and writes /proc/[pid]/maps files that contain listed
  25     mapped memory regions.
  26
  27 METHODS
  28
  29  read_maps
  30
  31     Read and parse a maps file, returning an arrayref of regions (each
  32     represented as a hashref). See "parse_maps_single_line" to see the
  33     format of the hashrefs.
  34
  35         my $regions = read_maps(%args);
  36
  37     Arguments:
  38
  39       * file - Path to maps file
  40
  41       * pid - Process ID (one of file or pid is required)
  42
  43       * mnt - Absolute path where proc(5) is mounted (optional, default:
  44       /proc)
  45
  46  write_maps
  47
  48     Returns a string with the contents of a maps file from the memory
  49     regions passed.
  50
  51         my $file_content = write_maps(\@regions, %args);
  52
  53     This is the opposite of "read_maps".
  54
  55     Arguments:
  56
  57       * fh - Write maps to this open file handle (optional)
  58
  59       * file - Open this filepath and write maps to that file (optional)
  60
  61  parse_maps_single_line
  62
  63     Parse and return a single line from a maps file into a region
  64     represented as a hashref.
  65
  66         my $region = parse_maps_single_line($line);
  67
  68     For example,
  69
  70         # address         perms offset  dev   inode   pathname
  71         08048000-08056000 r-xp 00000000 03:0c 64593   /usr/sbin/gpm
  72
  73     becomes:
  74
  75         {
  76             address_start   => 134512640,
  77             address_end     => 134569984,
  78             read            => 1,
  79             write           => '',
  80             execute         => 1,
  81             shared          => '',
  82             offset          => 0,
  83             device          => '03:0c'
  84             inode           => '64593',
  85             pathname        => '/usr/sbin/gpm',
  86         }
  87
  88  format_maps_single_line
  89
  90     Return a single line for a maps file from a region represented as a
  91     hashref.
  92
  93         my $line = format_maps_single_line(\%region);
  94
  95     This is the opposite of "parse_maps_single_line".
  96
  97 SEE ALSO
  98
  99     proc(5) describes the file format.
 100
 101 BUGS
 102
 103     Please report any bugs or feature requests on the bugtracker website
 104     https://github.com/chazmcgarvey/Linux-Proc-Maps/issues
 105
 106     When submitting a bug or request, please include a test-file or a patch
 107     to an existing test-file that illustrates the bug or desired feature.
 108
 109 AUTHOR
 110
 111     Charles McGarvey <chazmcgarvey@brokenzipper.com>
 112
 113 COPYRIGHT AND LICENSE
 114
 115     This software is copyright (c) 2016 by Charles McGarvey.
 116
 117     This is free software; you can redistribute it and/or modify it under
 118     the same terms as the Perl 5 programming language system itself.
 119