Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 [com-
       mand args]
       empty -w	[-Sv] [-t n] [-i fifo2 -o fifo1] key1 [answer1]	... [keyX  an-
       swerX]
       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 op-
       erations, 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 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 stan-
       dard 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	specitied with -o key, empty will try to find an auto-
		   matically 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 timeout.

       -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 spec-
		   ify pid, empty tries	to find	it within the list of automat-
		   ically  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.

       -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\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),	 some-
       times  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 do-
       ing.

       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 com-
       mand line while creating	this file, and certainly you should  set  some
       safe permissions	to this	file AND its directory (with the parent	direc-
       tories) before reading the password from	the file OR writing the	 pass-
       word 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	exter-
       nal 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)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | SECURITY | RETURN VALUES | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=empty&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help