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 <[email protected]>

COPYRIGHT AND LICENSE
   This software is copyright (c) 2019, 2015, 2014 by [email protected].

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.