# ps-node

> A process lookup utility

Latest version **0.1.6** (published 2017-04-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install ps-node
pnpm add ps-node
yarn add ps-node
bun add ps-node
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.6 |
| Published | 2017-04-21 |
| First published | 2012-12-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/ps-node) |
| Module format | CommonJS |
| Dependencies | 1 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 131 |
| Maintainers | neekey |
| Keywords | ps, process, lookup, pid |

## Links

- npm: https://www.npmjs.com/package/ps-node
- Repository: https://github.com/neekey/ps
- Homepage: https://github.com/neekey/ps#readme
- Issues: https://github.com/neekey/ps/issues
- npm.io page: https://npm.io/package/ps-node

## Dependencies (1)

- [table-parser](https://npm.io/package/table-parser.md) ^0.1.3

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 0.1.6 (latest) — 2017-04-21
- 0.1.5 — 2017-03-26
- 0.1.4 — 2016-10-18
- 0.1.3 — 2016-10-16
- 0.1.2 — 2016-06-23
- 0.1.1 — 2016-05-05
- 0.1.0 — 2016-05-04
- 0.0.5 — 2015-09-20
- 0.0.4 — 2015-04-16
- 0.0.3 — 2013-03-25
- 0.0.2 — 2012-12-28
- 0.0.1 — 2012-12-28

## README

# ps [![Build Status](https://travis-ci.org/neekey/ps.svg?branch=master)](https://travis-ci.org/neekey/ps) [![Build status](https://ci.appveyor.com/api/projects/status/fhom8ot12b6jxeyt?svg=true)](https://ci.appveyor.com/project/neekey/ps)

A Node.js module for looking up running processes. This module uses [Table-Parser](https://github.com/neekey/table-parser) to parse the output.

Before using this module, you should take look at section [Existing Bugs You Should Know](https://github.com/neekey/ps#user-content-existing-bugs-you-should-know) at the bottom of this doc.

## Install

```bash
$ npm install ps-node
```

## How Does It Work

This module uses different tools to get process list:

- Linux / Mac: use `ps` command. Since the default result from shell command `$ ps` will not contain "command arguments" in linux like "ubuntu", ps-node add arguments `lx` as default. Which means, the default value for option `psargs` is `lx`.
- Win: use command `wmic process get ProcessId,CommandLine` through "cmd", more info about wmic is [here](https://social.technet.microsoft.com/Forums/windowsserver/en-US/ab6c7e6e-4ad4-4237-bab3-0349cd76c094/wmic-command-line-utilities?forum=winservercore). Anyway, there is also another tool name [tasklist](https://technet.microsoft.com/en-us/library/bb491010.aspx) in windows, which can also list all the running processes, but lack of command arguments infomation. But compared to wmic, I think this tool should have a higher performance. You should take a look at the wrapper for this tool [tasklist](https://github.com/sindresorhus/tasklist) by @sindresorhs if you are interested.

## Compatibility

- Should work great in most *nix system.
- Should work on Win10/7 more system versions need to be test.  

Any compatibility issue is welcomed.

## Usage

Lookup process with specified `pid`:

```javascript
var ps = require('ps-node');

// A simple pid lookup
ps.lookup({ pid: 12345 }, function(err, resultList ) {
    if (err) {
        throw new Error( err );
    }

    var process = resultList[ 0 ];

    if( process ){

        console.log( 'PID: %s, COMMAND: %s, ARGUMENTS: %s', process.pid, process.command, process.arguments );
    }
    else {
        console.log( 'No such process found!' );
    }
});

```

Or use RegExp to filter `command` and `arguments`:

```javascript
var ps = require('ps-node');

// A simple pid lookup
ps.lookup({
    command: 'node',
    arguments: '--debug',
    }, function(err, resultList ) {
    if (err) {
        throw new Error( err );
    }

    resultList.forEach(function( process ){
        if( process ){

            console.log( 'PID: %s, COMMAND: %s, ARGUMENTS: %s', process.pid, process.command, process.arguments );
        }
    });
});

```

Also, you can use `kill` to kill process by `pid`:

```javascript
var ps = require('ps-node');

// A simple pid lookup
ps.kill( '12345', function( err ) {
    if (err) {
        throw new Error( err );
    }
    else {
        console.log( 'Process %s has been killed!', pid );
    }
});
```

Method `kill` also supports a `signal` option to be passed. It's only a wrapper of `process.kill()` with checking of that killing is finished after the method is called.

```javascript
var ps = require('ps-node');

// Pass signal SIGKILL for killing the process without allowing it to clean up
ps.kill( '12345', 'SIGKILL', function( err ) {
    if (err) {
        throw new Error( err );
    }
    else {
        console.log( 'Process %s has been killed without a clean-up!', pid );
    }
});
```

you can use object as the second parameter to pass more options:

```js
ps.kill( '12345', { 
    signal: 'SIGKILL',
    timeout: 10,  // will set up a ten seconds timeout if the killing is not successful
}, function(){});

```

Notice that the nodejs build-in `process.kill()` does not accept number as the signal, you will have to use string format.


You can also pass arguments to `lookup` with `psargs` as arguments for `ps` command（Note that `psargs` is not available in windows):

```javascript
var ps = require('ps-node');

// A simple pid lookup
ps.lookup({
    command: 'node',
    psargs: 'ux'
    }, function(err, resultList ) {
    if (err) {
        throw new Error( err );
    }

    resultList.forEach(function( process ){
        if( process ){
            console.log( 'PID: %s, COMMAND: %s, ARGUMENTS: %s', process.pid, process.command, process.arguments );
        }
    });
});

```

Lastly, you can filter a list of items by their PPID by passing a PPID to filter on. You will need to pass in a `psarg` that provides the PPID in the results (`-l` or `-j` for instance).

```javascript
var ps = require('ps-node');

// A simple pid lookup
ps.lookup({
    command: 'mongod',
    psargs: '-l',
    ppid: 82292
    }, function(err, resultList ) {
    if (err) {
        throw new Error( err );
    }

    resultList.forEach(function( process ){
        if( process ){
            console.log( 'PID: %s, COMMAND: %s, ARGUMENTS: %s', process.pid, process.command, process.arguments );
        }
    });
});

```

## Existing Bugs You Should Know

I'm still working on these bugs at the moment, before using this module in any serious way, please take a look at them, and take your own risk.

- [multiple-bytes characters may cause parse error](https://github.com/neekey/table-parser/issues/4).

---
_Source: https://npm.io/package/ps-node · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._