NAME

empty - run processes under pseudo-terminal sessions

SYNOPSIS

empty -f [-i fifo1 -o fifo2] [-p file.pid] [-x file.pid] [-L file.log] [-e [-t n]] command [command args]
empty -w [-Sv] [-t n] [-i fifo2 -o fifo1] key1 [answer1] ... [keyX answerX]
empty -s [-Sc] -o fifo1 [request]
empty -r [-b size] [-t n] [-i fifo2]
empty -l
empty -k [pid] [signal]
empty -h

DESCRIPTION

empty is an utility that provides a simple interface to processes executed under pseudo-terminal sessions. This tool is definitely useful in programming of shell scripts which are used to communicate with interactive command-line programs. In some cases empty can be a lightweight replacement TCL/expect or other similar programming tools.

There are several common forms of command lines for empty. But the first execution of empty is usually a start in the daemon mode to fork a new command (process) under PTY-session. This can be done with -f key. An interface for the input and output data channels of the forked process is made by two fifo-files which names may be specified with -i and -o keys. These files are automatically created/deleted any time you start/exit empty daemon, so there is no need to create them manually. If these fifo-files are not specified in the command line, empty names them by itself basing on its PID and PID of the forked PTY process.

At this point any application can easily communicate with forked process by writing data to the input fifo- and reading answers from the output fifo- files, see EXAMPLES section for details. To simplify this operations, empty offers an interfase to just send any data (use -s key), or even to watch the output fifo- for multiple keyphrases and reply to the input fifo- file with one of the responses (see -w key).

Note! Input fifo- for empty -f ... is usually an output fifo- file for empty -w and empty -s forms. And output fifo- of empty -f ... is an input fifo-file for empty -w ...

If something goes wrong the forked process may be killed by the standard kill command, or using -k key of empty. See -p option to save PID of empty daemon process. -x option to save forked child process PID.

The following options are available:

-f

fork, spawn, start or execute a new process specified by the command and its arguments. If you omit fifo-files, empty with its job control algorithm will create them under /tmp directory using this templates: empty.PPID.PID.in and empty.PPID.PID.out, here PPID is usually your shell system process ID and PID is system process ID of empty-daemon.

-s

send data (request) to the forked process. If fifo file was not specitied with -o key, empty will try to find an automatically created fifo file it in /tmp directory. Instead of command line you can send your request or data directly to standard input (stdin) of empty

-w

watch for one or more keyphrases and if specified send the appropriated response to the input fifo. If response is not set, empty waits for the proper keyphrase then exits. With -w key empty returns the number of matched keyphrase-response pair, or 255 if fails to find this match (see -t key for details of possible exit on timeout).

-r

read from output fifo-file one line (default) or one block of data (if -b size was specified). If -t n key was placed, exit on timeout.

-l

list automatically created jobs. NB! Custom jobs, which fifo-files specified with -i and -o keys, are not displayed. So if none fifo-files are specified with -i and -o keys all operations are done under the job marked current

-k

send signal to the process with pid. If pid is not specified, empty tries to find it within the list of automatically created jobs. If signal is omitted the default SIGTERM is used.

-h

print short help message and exit

-i fifo1

a fifo-file, which is used as input for a forked process.

-o fifo2

a fifo-file, which is used as output for a forked process.

-L file.log

This option allows to log the whole empty session to a file. Marks >>> and <<< show the directions of data flow.

-e

forces empty to keep output fifo-alive alive if some data left in it

-p file.pid

Save PID of empty daemon process to a file

-t n

If used with -w key. If input fifo-file is empty, wait for n seconds to receive the keyphrase then exit on timeout with 255 code.

If used with -e key. Wait -n seconds before deleting non-empty output fifo-file if the forked process ended.

-c

force empty to use stdin for data or requests.

-S

Strip the last character from the input. Works with -s and -w keys

-v

kvazi verbose mode. Show all contents of received buffer.

EXAMPLES

Start a new PTY-session with telnet to localhost:

	empty -f -i in.fifo -o out.fifo -p empty.pid -L empty.log telnet localhost

Interact with telnet:

	empty -w -i out.fifo -o in.fifo ogin 'my_user\n'
	empty -w -i out.fifo -o in.fifo assword 'my_password\n'

Send commands to telnet with empty:

	empty -s -o in.fifo who
	empty -s -o in.fifo "ls -la /\n"

The same using STDIN:

	echo who | empty -s -o in.fifo
	echo "ls -la /" | empty -s -o in.fifo

Just cat output from telnet:

	cat out.fifo

Read one line from out.fifo:

	empty -r -i out.fifo 

Send commands to telnet with ordinary echo:

	echo "who am i" > in.fifo
	echo "uname -a" > in.fifo

Kill a process with PID 1234:

	empty -k 1234
or
	kill 1234


    

Telnet session with automatically created jobs:

	empty -f telnet localhost

Interact with telnet using job control:

	empty -w ogin 'my_user\n'
	empty -w assword 'my_password\n'

List automatically created jobs:

	empty -l
	PPID    PID     TYPE    FILENAME
	479     706     in      /tmp/empty.479.706.in
	479     706     out     /tmp/empty.479.706.out
	479     711     in      /tmp/empty.479.711.in
	479     711     out     /tmp/empty.479.711.out
	479     711     current

SECURITY

It is considered insecure to send a password in the command line like this:

	
	empty -w assword 'my_password\n'

or like this:

	empty -s 'my_password\n'

The reason is that the command line arguments are visible to the system while empty is running. Any local user can see them with ps(1), sometimes they are visible even remotely with finger(1). Also your server may have some monitoring tools which may store the output from ps(1) in their logs. There are also other, more complicated ways to compromise this information. Generally, you should take command line arguments as (possibly) visible to every one unless you really know what you're doing.

empty with '-s' flag runs quickly in most cases, but still it can hang for a number of reasons (like fifo overloading), and even if it runs quick you still cannot be sure that no one will see its command line arguments even in this short time. empty with '-w' flag is even worse because it must wait for the keyphrase.

A better way to send the password to the supervised program is to read it from file:

	empty -s [common options] <./password-file

	get-password-of-user "$user" |empty -s [common options]

Another possible way is to use your shell's builtin (but see below):

	echo "$password" |empty -s [common options]

RETURN VALUES

If any error occurs empty usually exits with code 255. Otherwise zero or some positive value (see -w key) is returned.

SEE ALSO

expect(1), chat(8)

AUTHOR

empty was made by Mikhail Zakharov. This software was based on the basic idea of pty version 4.0 Copyright (c) 1992, Daniel J. Bernstein but no code was ported from pty4. SECURITY section of this manual page was contributed by Sergey Redin.