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