1 package Linux
::Proc
::Maps
;
2 # ABSTRACT: Read and write /proc/[pid]/maps files
3 # KEYWORDS: linux proc procfs
8 our $VERSION = '999.999'; # VERSION
11 use Exporter
qw(import);
12 use namespace
::clean
-except
=> [qw(import)];
14 our @EXPORT_OK = qw(read_maps write_maps parse_maps_single_line format_maps_single_line);
18 use Linux::Proc::Maps qw(read_maps);
21 my $vm_regions = read_maps(pid => $$);
23 # by pid with explicit procfs mount:
24 my $vm_regions = read_maps(mnt => '/proc', pid => 123);
27 my $vm_regions = read_maps(file => '/proc/456/maps');
31 This module reads and writes F</proc/[pid]/maps> files that contain listed mapped memory regions.
35 Read and parse a maps file, returning an arrayref of regions (each represented as a hashref). See
36 L</parse_maps_single_line> to see the format of the hashrefs.
38 my $regions = read_maps(%args);
43 * C<file> - Path to maps file
44 * C<pid> - Process ID (one of C<file> or C<pid> is required)
45 * C<mnt> - Absolute path where L<proc(5)> is mounted (optional, default: C</proc>)
50 my %args = @_ == 1 ? (pid
=> $_[0]) : @_;
52 my $file = $args{file
};
54 if (!$file and my $pid = $args{pid
}) {
55 if ($pid =~ /^\d+$/) {
56 require File
::Spec
::Functions
;
57 my $procfs = $args{mnt
} || $ENV{PERL_LINUX_PROC_MAPS_MOUNT
} ||
58 File
::Spec
::Functions
::catdir
(File
::Spec
::Functions
::rootdir
(), 'proc');
59 $file = File
::Spec
::Functions
::catfile
($procfs, $pid, 'maps');
66 $file or croak
'Filename or PID required';
67 open(my $fh, '<:encoding(UTF-8)', $file) or croak
"Open failed ($file): $!";
71 while (my $line = <$fh>) {
74 my $region = parse_maps_single_line
($line);
77 push @regions, $region;
85 Returns a string with the contents of a maps file from the memory regions passed
.
87 my $file_content = write_maps
(\
@regions, %args);
89 This
is the opposite of L
</read_maps
>.
94 * C<fh> - Write maps to this open file handle (optional)
95 * C<file> - Open this filepath and write maps to that file (optional)
100 my $regions = shift or croak
'Regions required';
103 ref $regions eq 'ARRAY' or croak
'Regions must be an arrayref';
107 for my $region (@$regions) {
108 $out .= format_maps_single_line
($region);
111 # maybe print out the memory regions to a filehandle
113 if (!$fh and my $file = $args{file
}) {
114 open($fh, '>:encoding(UTF-8)', $file) or croak
"Open failed ($file): $!";
116 print $fh $out if $fh;
121 =method parse_maps_single_line
123 Parse
and return a single line from a maps file into a region represented as a hashref
.
125 my $region = parse_maps_single_line
($line);
129 # address perms offset dev inode pathname
130 08048000-08056000 r-xp
00000000 03:0c
64593 /usr/sbin
/gpm
135 address_start
=> 134512640,
136 address_end
=> 134569984,
144 pathname
=> '/usr/sbin/gpm',
149 sub parse_maps_single_line
{
150 my $line = shift or croak
'Line from a maps file required';
154 my ($addr1, $addr2, $read, $write, $exec, $shared, $offset, $device, $inode, $pathname) = $line =~ m
{
156 ([[:xdigit
:]]+)-([[:xdigit
:]]+)
157 \s
+ ([r-
])([w-
])([x-
])([sp
])
159 \s
+ ([[:xdigit
:]]+:[[:xdigit
:]]+)
166 no warnings
'portable'; # for hex() on 64-bit perls
169 address_start
=> hex($addr1),
170 address_end
=> hex($addr2),
171 read => 'r' eq $read,
172 write => 'w' eq $write,
173 execute
=> 'x' eq $exec,
174 shared
=> 's' eq $shared,
175 offset
=> hex($offset),
178 pathname
=> $pathname || '',
182 =method format_maps_single_line
184 Return a single line
for a maps file from a region represented as a hashref
.
186 my $line = format_maps_single_line
(\
%region);
188 This
is the opposite of L
</parse_maps_single_line
>.
192 sub format_maps_single_line
{
193 my $region = shift or croak
'Region required';
195 my @args = @{$region}{qw(address_start address_end read write execute shared offset device inode)};
196 $args[2] = $args[2] ? 'r' : '-';
197 $args[3] = $args[3] ? 'w' : '-';
198 $args[4] = $args[4] ? 'x' : '-';
199 $args[5] = $args[5] ? 's' : 'p';
201 return sprintf("%-72s %s\n", sprintf("%x-%x %s%s%s%s %08x %s %d", @args), $region->{pathname
});
206 L<proc(5)> describes the file format.