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.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 mapped memory regions.
  25
  26 # METHODS
  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 # BUGS
  93
  94 Please report any bugs or feature requests on the bugtracker website
  95 [https://github.com/chazmcgarvey/Linux-Proc-Maps/issues](https://github.com/chazmcgarvey/Linux-Proc-Maps/issues)
  96
  97 When submitting a bug or request, please include a test-file or a
  98 patch to an existing test-file that illustrates the bug or desired
  99 feature.
 100
 101 # AUTHOR
 102
 103 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 104
 105 # COPYRIGHT AND LICENSE
 106
 107 This software is copyright (c) 2016 by Charles McGarvey.
 108
 109 This is free software; you can redistribute it and/or modify it under
 110 the same terms as the Perl 5 programming language system itself.