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

   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 mapped memory regions.
  25
  26 # FUNCTIONS
  27
  28 ## read\_maps
  29
  30 Read and parse a maps file, returning an arrayref of regions (each represented as a hashref). See
  31 ["parse\_maps\_single\_line"](#parse_maps_single_line) to see the format of the hashrefs.
  32
  33     my $regions = read_maps(%args);
  34
  35 Arguments:
  36
  37 - `file` - Path to maps file
  38 - `pid` - Process ID (one of `file` or `pid` is required)
  39 - `mnt` - Absolute path where [proc(5)](http://man.he.net/man5/proc) is mounted (optional, default: `/proc`)
  40
  41 ## write\_maps
  42
  43 Returns a string with the contents of a maps file from the memory regions passed.
  44
  45     my $file_content = write_maps(\@regions, %args);
  46
  47 This is the opposite of ["read\_maps"](#read_maps).
  48
  49 Arguments:
  50
  51 - `fh` - Write maps to this open file handle (optional)
  52 - `file` - Open this filepath and write maps to that file (optional)
  53
  54 ## parse\_maps\_single\_line
  55
  56 Parse and return a single line from a maps file into a region represented as a hashref.
  57
  58     my $region = parse_maps_single_line($line);
  59
  60 For example,
  61
  62     # address         perms offset  dev   inode   pathname
  63     08048000-08056000 r-xp 00000000 03:0c 64593   /usr/sbin/gpm
  64
  65 becomes:
  66
  67     {
  68         address_start   => 134512640,
  69         address_end     => 134569984,
  70         read            => 1,
  71         write           => '',
  72         execute         => 1,
  73         shared          => '',
  74         offset          => 0,
  75         device          => '03:0c'
  76         inode           => '64593',
  77         pathname        => '/usr/sbin/gpm',
  78     }
  79
  80 ## format\_maps\_single\_line
  81
  82 Return a single line for a maps file from a region represented as a hashref.
  83
  84     my $line = format_maps_single_line(\%region);
  85
  86 This is the opposite of ["parse\_maps\_single\_line"](#parse_maps_single_line).
  87
  88 # SEE ALSO
  89
  90 [proc(5)](http://man.he.net/man5/proc) describes the file format.
  91
  92 # CAVEATS
  93
  94 Integer overloading may occur if you try to parse memory regions from address spaces larger than
  95 your current architecture (or perl) supports. This is currently not fatal, though you will get
  96 warnings from perl that you probably shouldn't ignore.
  97
  98 # BUGS
  99
 100 Please report any bugs or feature requests on the bugtracker website
 101 [https://github.com/chazmcgarvey/Linux-Proc-Maps/issues](https://github.com/chazmcgarvey/Linux-Proc-Maps/issues)
 102
 103 When submitting a bug or request, please include a test-file or a
 104 patch to an existing test-file that illustrates the bug or desired
 105 feature.
 106
 107 # AUTHOR
 108
 109 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 110
 111 # COPYRIGHT AND LICENSE
 112
 113 This software is copyright (c) 2016 by Charles McGarvey.
 114
 115 This is free software; you can redistribute it and/or modify it under
 116 the same terms as the Perl 5 programming language system itself.