Skip to content
Tutorials Center
My learning

Topics

Lesson 124 of 201 ยท Input and Output

Running External Processes

Learn how to run external programs from Java with ProcessBuilder - read output, feed input, merge stderr, check exit codes, set timeouts, environment variables and avoid deadlocks.

Sometimes the best way to get something done is not to write it in Java at all. You might want to call git to get the current commit, ffmpeg to convert a video, a Python script that already works, or a shell command that lists disk usage. Java can start any program on the machine, give it input, read what it prints and find out whether it succeeded. The class for this is ProcessBuilder, which creates a Process.

This lesson shows how to launch a command safely, read its output (both normal output and errors), send it input, interpret exit codes, stop it when it takes too long, and avoid the classic deadlock that hangs your program. The examples use common Unix tools such as echo, sort and sh because they exist on the server that runs this page. On Windows, use the equivalent (for example cmd /c instead of sh -c).

The three pipes

A running program has three standard streams: stdin (input), stdout (normal output) and stderr (error messages). When Java starts a child process, it connects pipes to these streams. Note the direction of the names, which confuses almost everyone: from your Java program's point of view, the child's output is something you read (getInputStream()), and the child's input is something you write (getOutputStream()).

flowchart LR
    subgraph Java["Your Java program"]
        W["process.getOutputStream()<br/>you write"]
        R1["process.getInputStream()<br/>you read"]
        R2["process.getErrorStream()<br/>you read"]
    end
    subgraph Child["Child process"]
        I["stdin"]
        O["stdout"]
        E["stderr"]
    end
    W --> I
    O --> R1
    E --> R2

The child's stdout arrives in Java as an InputStream, and Java's OutputStream feeds the child's stdin.

Starting a process and reading its output

You give ProcessBuilder the command as separate arguments (a program name followed by its arguments, each as its own string), call start(), read the output and wait for the process to finish.

Java Run a command and read its output

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Three things to note:

  • The command is not one string like "echo Hello". Java does not split it for you and does not use a shell. Each element of the list is exactly one argument, so spaces and quotes inside an argument are safe.
  • readAllBytes() reads until the child closes its stdout, which normally happens when it exits.
  • waitFor() blocks until the process ends and returns its exit code: 0 means success by convention, anything else means some kind of failure.

If the program does not exist, start() itself throws an IOException (the message starts with "Cannot run program" and names the missing file), before any process is created.

Exit codes and standard error

Programs report problems in two ways: an exit code that is not zero, and a message on stderr. A well-written wrapper checks both. The easiest way to see everything is redirectErrorStream(true), which merges stderr into stdout so you read one stream, in the order the child wrote it.

Java Exit codes and merged error output

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

If you want stdout and stderr separately, don't merge them, but then you must read both streams at the same time (next section explains why). A simpler alternative is to send one of them to a file with redirectError(new File("errors.log")) or Redirect.DISCARD.

The deadlock trap

A pipe has a small buffer, often 64 KB. If the child writes more than that and your program isn't reading, the child blocks waiting for space. If your program is waiting for the child to exit before it reads, you have a deadlock: both sides wait for each other forever.

sequenceDiagram
    participant J as Java
    participant C as Child process
    J->>C: start()
    J->>C: waitFor() (Java is blocked)
    C->>C: writes a lot to stdout
    Note over C: pipe buffer full,<br/>child blocks on write
    Note over J,C: Neither side can continue: deadlock

Never call waitFor() before you have consumed the output, if the output can be large.

The rules that avoid it:

  1. Read first, then waitFor() (as in the examples above: readAllBytes() returns when the child closes the stream).
  2. If you need stdout and stderr separately, either read one of them on another thread, or redirect one to a file or Redirect.DISCARD.
  3. If you don't care about the output at all, say so: redirectOutput(ProcessBuilder.Redirect.DISCARD).

The most convenient trick when you only want to see the output on screen is inheritIO(), which gives the child your program's own stdin, stdout and stderr. Nothing flows through Java, so nothing can fill a buffer.

Sending input to a process

To feed the child's stdin, write to getOutputStream() and close it. Closing sends end-of-file; programs like sort and wc wait for it before producing their result.

Java Sending input to sort

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

In this example the input is small and written before reading. For large amounts of data in both directions, write on one thread and read on another so neither pipe blocks.

Pipelines

Unix users chain programs with |. In Java, ProcessBuilder.startPipeline(List<ProcessBuilder>) connects the stdout of each process to the stdin of the next, without any data passing through your program:

Java A pipeline: printf, then sort, then uniq

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

You read only the last process's output; the earlier ones are connected by the operating system.

Working directory and environment variables

Every process has a working directory and a set of environment variables. By default the child inherits both from your Java program, and you can change them on the builder:

Java Directory and environment

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

environment() returns a copy of your environment that you can change; edits affect only that builder's children, never your own program.

Timeouts and stopping a process

Never wait forever for a child you don't control. waitFor(timeout, unit) returns false if the process is still running when time is up. Then stop it:

  • destroy() politely asks the process to end (SIGTERM on Unix).
  • destroyForcibly() kills it immediately (SIGKILL on Unix). Follow it with a waitFor() so the process is really gone.
Java Giving up on a slow command

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

exitValue() throws IllegalThreadStateException if the process is still running, so check isAlive() or waitFor first. On Unix, a process killed by a signal reports 128 + signal number, so 137 for SIGKILL.

Reacting asynchronously with onExit

process.onExit() returns a CompletableFuture<Process> that completes when the process ends, so you can attach a callback instead of blocking a thread (see CompletableFuture). The ProcessHandle interface adds the process id, parent, children, start time and the command line: process.pid(), ProcessHandle.current(), ProcessHandle.allProcesses().

Security: never build a command from user input

The most dangerous way to use ProcessBuilder is to pass user text to a shell:

Java
// DANGEROUS: if userFile is "x; rm -rf ~", the shell runs both commands
new ProcessBuilder("sh", "-c", "cat " + userFile).start();

This is command injection. The safe version has no shell and no string gluing, so the user text is just one argument that cannot become a command:

Java
new ProcessBuilder("cat", userFile).start();

Even then, validate the value (a user file name might start with - and look like an option to the program; -- before it is one defence). Prefer a Java library over a command whenever one exists: Java can read files, make HTTP calls and compress data itself, and that is faster and portable.

Note: Processes make your program less portable. ls, sh and sleep don't exist on a default Windows machine, and options differ between versions of a tool. Document what your program needs, and check System.getProperty("os.name") if you must support both.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In your Java program, which method do you call to read what the child process printed to stdout?

    Names are from Java's point of view: the child's output is an InputStream you read, and getOutputStream() is the pipe you write the child's input into.
  2. 2. Why can calling waitFor() before reading a chatty child's output hang forever?

    Pipes have small buffers. When the buffer is full the child waits for you to read, and you are waiting for the child: a deadlock.
  3. 3. Which call is safe against command injection when name comes from a user?

    Passing the value as its own argument without a shell means it can never be interpreted as a second command.
  4. 4. You want to feed a program some input and make it finish reading. What must you do after writing to getOutputStream()?

    Programs like sort wait for end-of-file on stdin. Closing the output stream sends it.

Summary

  • new ProcessBuilder("program", "arg1", "arg2").start() launches a program; every argument is its own string and no shell is involved.
  • The child's stdout and stderr are InputStreams for you (getInputStream(), getErrorStream()); its stdin is the OutputStream you write to, and you must close it to signal end of input.
  • Read the output before (or while) you waitFor(); use redirectErrorStream(true), redirects to files, Redirect.DISCARD or inheritIO() to avoid pipe deadlocks.
  • Exit code 0 is success; always check it. Use waitFor(timeout, unit) plus destroyForcibly() for processes you don't trust to finish.
  • directory() and environment() configure where and with which variables the child runs; startPipeline chains processes.
  • Never put untrusted text into a sh -c string; pass it as a separate argument or avoid the external command entirely.

Next: Threads, where you'll run several tasks inside your own Java program at the same time.