empty(1)						      General Commands Manual							  empty(1)

NAME

       empty - run processes under pseudo-terminal sessions

SYNOPSIS

       empty -f [-i fifo1 -o fifo2] [-p file.pid] [-L file.log] 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 execute and/or interact with processes under pseudo-terminal sessions. This tool is
       definitely useful in programming of shell scripts which are used to communicate with interactive programs like telnet or ftp. In some cases
       empty can be a substitution for 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 performed 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 you must not create them manually. If you did not specify these fifo files in the command line,  empty
       names them by itself basing on its PID and PID of 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, see EXAMPLES section for the details. To simplify this operations, empty offers an interface to just send  any  data  (use	-s
       key), or even to watch the output fifo for multiple keyphrases and reply to the input fifo with one of the responses (see -w key).

       Note!  Input fifo for empty -f ...  is usually an output fifo for empty -w and empty -s forms. And output fifo of empty -f ...  is an input
       fifo 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.

       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 specified 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 one line (default) or one block of data (if -b size was specified). If -t n key was placed, exit on time-
		   out.

       -l	   list automatically created jobs by your shell.  NB!	Your custom jobs, which fifo files you specified with -i and -o keys,  are
		   not displayed. So if you did not specify fifo files with -i and -o keys all operations are done under the job marked current

       -k	   send  signal to the process with pid.  If you did not specify pid, empty tries to find it within the list of automatically cre-
		   ated 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.

       --logfile-mode=mode
		   This option allows to choose the mode of the log file created with the -L option.  The default mode is 0600.

       -p file.pid Save PID of empty daemon process to a file

       -t n	   If input FIFO is empty, wait for n seconds (default is 10) to receive the keyphrase then exit on timeout with 255 code.

       -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
'
	    empty -w -i out.fifo -o in.fifo assword 'my_password
'

       Send commands to telnet with empty:
	    empty -s -o in.fifo who
	    empty -s -o in.fifo "ls -la /
"

       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
'
	    empty -w assword 'my_password
'

       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
'

       or like this:

	    empty -s 'my_password
'

       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

       or from a pipe:

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

       You  should  still make sure that you do not send any password via command line while creating this file, and certainly you should set some
       safe permissions to this file AND its directory (with the parent directories) before reading the password from  the  file  OR  writing  the
       password to it.

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

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

       Many  shells like bash(1), csh(1) and FreeBSD's sh(1) do not call external echo(1) command but use their own builtin echo command. Since no
       external command is started (the shell itself does all that echo(1) must do), nothing is shown in the process list. It is beyond this  man-
       ual page to discuss the way to make sure that your shell uses the builtin command.

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 E. 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.

								  March, 05 2006							  empty(1)