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] [-x file.pid] [-L file.log]
       [-e [-t n]] command [command 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	processes exe-
       cuted under pseudo-terminal sessions. This tool is definitely useful in
       programming of shell scripts which are used to communicate with	inter-
       active  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 re-
       ply 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 stan-
       dard 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	 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-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  dis-
		   played.  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	speci-
		   fied,  empty	 tries to find it within the list of automati-
		   cally 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),	 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 Zakharov. This	software was based on the  ba-
       sic 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.

			       December, 31 2022		      empty(1)

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

home | help