For example, the following command
example$ faucet 3000 --out --verbose --once --foreignhost client echo blah
could be written
example$ faucet 3000 -ov1h client echo blah
The -p, -h, and -H flags take an argument, but the flags may be grouped into one argument. They then grab the arguments they need from the command line in the order the flags appear.
example$ faucet 3000 -hpHov1 client 2999 example-le2 echo blah
Whereas each --fd word flag required an individual descriptor, the -# character flag can take multiple descriptors. The following are equivalent:
example$ faucet 3000 --fd 0 --fd 1 --verbose --once echo blah example$ faucet 3000 -#0,1v --once echo blah example$ faucet 3000 -v1#0,1 echo blah example$ faucet 3000 -#0,1v1 echo blah
Note that you have to pay attention when using the -# character flag and the -1 character flag in the same argument. Also, remember the special shutdown(2) semantics of -in and -out.
This creates a TCP-IP socket on the local machine bound to port 3000.
example$ faucet 3000 --out --verbose tar -cf - .
Every time some process (from any machine) attempts to connect to port 3000 on this machine the faucet program will fork(2) a process and the child will exec(2) a
tar -cf - .
The --out option means that the output of the child process will have been redirected into the new socket retrieved by the accept(2) call. --verbose means that faucet will print information about each new connection.
This creates a UNIX domain socket in the current directory
example$ faucet u-socket --out --err --once --unix csh -c \ "dd if=angio.pgm | funky.perl.script"
The --out --err option means that stdout and stderr will be redirected in the child process. The --once option means that the faucet will not fork(2), but exec(2) the process so that only the first process can connect to the u-socket before the faucet becomes unavailable.
This example listens on a socket until the first connection comes through. It then spawns a bidirectional copy that is similar to hose -slave.
faucet 3000 -1v --fd 3 sh -c cat <&3 & cat >&3 ; sockdown 3
netpipes(1), hose(1), sockdown(1), getpeername(1), socket(2), bind(2), listen(2), accept(2), shutdown(2), services(5), gethostbyaddr(3)
There is a problem with almost every OS I have used faucet on. Ports are sometimes not recycled swiftly enough. If you kill one faucet and try to start another that wants to listen on the same port you will often see pre-4.1 faucets print the following warning over and over again:
faucet: Address 3000 in use, sleeping 10. faucet: Trying again . . .
but you wont actually be able to connect(2) to that port (with hose(1), for example) because youll get a connection refused.
There was also an experimental Linux kernel that NEVER recycled ports (I quickly switched back to my old kernel).
I have been informed that this is a side-effect of the TCP specification and that I should use the SO_REUSEADDR option to work around it, so I do.
Doubtless there are bugs in this program, especially in the unix domain socket portions. I welcome problem reports and would like to make these programs as "clean" (no leftover files, sockets) as possible.
4.1 added --backlog and --noreuseaddr. --noreuseaddr reflects the fact that 4.1 also added the SO_REUSEADDR socket option as the default.
4.0 made the full-word arguments use -- like many GNU programs. They are still available with a single - for backward-compatibility.
3.1 added the single-character flags and the -pidfile option. It also switched to the setsid(2) system call to detach itself from the process group for the -daemon flag. Ive been hacking at UNIX for years, but there are still some things that I never really learned, and others that have been changing. I need to buy a book.
Release 2.3 added support for multi-homed hosts: hosts with multiple internet numbers (such as gateways). Before this faucet assumed that the first internet number that gethostbyname returned was the only one. --foreignhost authentication was weakened by this inadequacy so I beefed up the algorithms. --foreignhost will accept a connection from any of the internet numbers associated with the host name.
Thanks to Steve Clift <firstname.lastname@example.org> for SGI (SysV) patches.
Many people complained about the old way of specifying the command. Thanks to whoever gave me the alternative which is now implemented. It is much better.
Randy Fischer <email@example.com> finally prodded me into fixing the old lame non-handling of multi-homed host.
Thanks to all who suggested I use setsid() for -daemon mode.
Thanks to the Spring 1996 UF CIS consulting staff <firstname.lastname@example.org> for pointing out the sys_errlist declaration conflict on FreeBSD. Sometimes I hate Sun Microsystems.
Thanks to Daniel OConnor <email@example.com> for suggesting the -pidfile flag.
Big thanks to Joe Traister <firstname.lastname@example.org> for his signal handling patches, strerror surrogate, and other assorted hacks.
Thanks to Thomas A. Endo <email@example.com> for dropping an SO_REUSEADDR patch in my lap. Otherwise I wouldnt have gotten to it till 2001.
Copyright (C) 1992-98 Robert Forsman
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
Purple Frog Software
|-->||FAUCET (1)||October 28, 1998|