The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Proc::Find - Find processes by name, PID, or some other attributes

VERSION

This document describes version 0.051 of Proc::Find (from Perl distribution Proc-Find), released on 2019-11-23.

SYNOPSIS

 use Proc::Find qw(find_proc proc_exists);

 # list all of a user's processes
 my $procs = find_proc(user=>'ujang', detail=>1);

 # check if a program is running
 die "Sorry, xscreensaver is not running"
     unless proc_exists(name=>'xscreensaver').

DESCRIPTION

This module provides a simple routine, proc_exists(), to check a process' existence by name, something that is commonly done in shell scripts using:

 ps ax | grep name
 pgrep name

and also some routines, find_*(), to list processes matching some criteria.

VARIABLES

$Proc::Find::CACHE => bool (default: 0)

If set to true, will cache the call to Proc::ProcessTable's table() so subsequent invocation to find_proc() or proc_exists doesn't have to call the method again. But this also means that the process check/listing will be done on a past/stale process table.

FUNCTIONS

find_proc(%args) => \@pids (or \@procs)

Find process by name, PID, or some other attributes. Return an arrayref of PID's, or an empty arrayref if none match the criteria.

Currently use Proc::ProcessTable to list the processes.

Arguments:

  • filter => code

    Filter by a coderef. The coderef will receive the process record (hashref).

  • pid => int|array[int]|regex

    Find by PID. Note that if you only want to check whether a PID exists, there are cheaper methods (see "SEE ALSO").

  • name => str|array[str]|regex

    Match against process' "name". Name is taken from the first word of the cmndline, with path stripped.

    If value is regex, will do a regex match instead of exact string comparison.

    Example:

     find_proc(name => "bash")
     find_proc(name => qr/^(Thunar|dolphin|konqueror)$/)
  • cmndline => str|array[str]|regex

    Match against full cmndline.

    If value is regex, will do a regex match instead of exact string comparison.

  • exec => str|array[str]|regex

    Match against program (executable/binary)'s path. If value does not contain a path separator character, will be matched against program's name.

    Example:

     find_proc(exec => "perl")          # find any perl
     find_proc(exec => "/usr/bin/perl") # find only a specific perl
  • user => int|str|array[int|str]|regex

    List processes owned by specified user/UID.

    If given a username which does not exist, will simply not match.

  • uid => int|str|array[int|str]|regex

    Same as user.

  • euser => int|str|array[int|str]|regex

    List processes running as certain effective user/UID (will look against euid).

    If given a username which does not exist, will simply not match.

  • euid => int|str|array[int|str]|regex

    Same as euser.

  • inverse => bool

    If set to true, then will return all processes not matching the criteria.

  • table => obj

    Supply result from Proc::ProcessTable object's table(). This can be used to reuse the table() cached result instead of repeatedly call table() on every invocation.

    See also $Proc::Find::CACHE.

  • detail => bool (default: 0)

    Instead of returning just the PID for each result, return a hash (record) of process information instead. Currently this is just the entry from Proc::ProcTable object's table() result.

proc_exists(%args) => bool

Shortcut for:

 @{ find_proc(%args) } > 0

find_all_proc(\%args, \%args2, ...) => \@pids (or \@procs)

Given multiple criteria, perform an AND search. Will only call Proc::ProcessTable's table() method once.

 # find all processes matching mutiple criteria (although the same thing can
 # also be accomplished by find_proc() and combining the criteria)
 find_all_proc([{name=>'mplayer'}, {cmndline=>qr/mp3/}]);

find_any_proc(\%args, \%args2, ...) => \@pids (or \@procs)

Given multiple criteria, perform an OR search. Will only call Proc::ProcessTable's table() method once.

 # find all processes belonging to either user
 find_any_proc([{user=>'ujang'}, {user=>'titin'}]);

HOMEPAGE

Please visit the project's homepage at https://metacpan.org/release/Proc-Find.

SOURCE

Source repository is at https://github.com/perlancar/perl-Proc-Find.

BUGS

Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Proc-Find

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

SEE ALSO

Proc::Exists can be used to check if one or more PIDs exist. If you are only concerned with POSIX systems, you can just do kill 0, $pid to accomplish the same.

pgrep Unix command.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019, 2015, 2014 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.