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.002
   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 FUNCTIONS
  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 CAVEATS
 102
 103     Integer overloading may occur if you try to parse memory regions from
 104     address spaces larger than your current architecture (or perl)
 105     supports. This is currently not fatal, though you will get warnings
 106     from perl that you probably shouldn't ignore.
 107
 108 BUGS
 109
 110     Please report any bugs or feature requests on the bugtracker website
 111     https://github.com/chazmcgarvey/Linux-Proc-Maps/issues
 112
 113     When submitting a bug or request, please include a test-file or a patch
 114     to an existing test-file that illustrates the bug or desired feature.
 115
 116 AUTHOR
 117
 118     Charles McGarvey <chazmcgarvey@brokenzipper.com>
 119
 120 COPYRIGHT AND LICENSE
 121
 122     This software is copyright (c) 2016 by Charles McGarvey.
 123
 124     This is free software; you can redistribute it and/or modify it under
 125     the same terms as the Perl 5 programming language system itself.
 126