CONNECT(1) CONNECT(1)
NAME
connect - multi functional network connector
SYNOPSIS
connect [options] mode-arguments
DESCRIPTION
connect is a multi mode network connector. It can act on
the client and server side to connect the other end of the
network connection to a local program or file. It's main
purpose is to provide gawk or other similiar scripting
languages with certain TCP/IP networking features.
OPERATION MODES
Client Mode
connect expects the address of the connections remote end
as mode argument. After the connections has been estab-
lished connect writes everything it reads on it's stdin to
the remote end and write everyhting to stdout that is sent
by the remote end.
connect can be used in this `network pipe' mode as a co-
process. Instead of doing the TCP/IP directly from within
gawk
print "Hello World!" |& "/inet/tcp/0/server/port";
the construct
print "Hello World!" |& "connect server:port";
does the same but with network connection timeout han-
dling.
Server Mode
The server mode is entered if the -s option is found on
the command line. It's typically used from within inetd
with a configuration line like:
port stream tcp nowait nobody \
/usr/local/bin/connect connect -s server args
In server mode connect expects a server program and
optional server arguments on it's command line. The
server is started with it's stdin/stdout connected to the
remote (client) end of the connection.
The differences between using connect and configuring the
server to be started directly from inetd are that (1) con-
nect adds again timeout handling and (2) connect provides
the server with the connection details in the following
environment variables.
CONNECT_INTERFACE, CONNECT_PORT
is the local interface address and port of the net-
work connection.
connection has been established connect closes the lis-
tener port and continues processing in the client mode.
If the interface part is missing connect allocates the
port on any local interface (the interface address is set
to `0.0.0.0'). If the port is missing or `0' the port is
dynamically choosen.
Both, the local and remote, interface/port information is
printed on connect's stdout to provide this information to
the calling process.
INPUT/OUTPUT HANDLING
Input/Output Redirection
connect uses sometimes it's own stdin/stdout for communi-
cation with it's calling process. So it's not always pos-
sible to use standard shell stdin/stdout redirection to
write to or read from files.
To make connect write the connection's output data to a
file instead from stdout you can use the `-w filename'
option. This option is useful for FTP-DATA mode.
The `-r filename' does the same for the connection's input
data: it's read from filename instead of stdin.
Connecting a Program
In client or FTP-DATA mode connect can connect a program
to the connection's remote end:
connect -p ... program [arg ...]
After the connection has been established connect starts
program (given by the remaining command line arguments)
with the given optional arguments and connects program's
stdin/stdout to the remote end of the connection.
In this case connect provides the following environment
variables to program:
CONNECT_PID
connect's process id.
CONNECT_INTERFACE, CONNECT_PORT
is the local interface address and port of the net-
work connection.
CONNECT_REMOTE, CONNECT_REMOTE_PORT
is the same as above but this time for the remote
end (the client).
CONNECT_STDIN, CONNECT_STDOUT
these are filedescriptor numbers of connect's
stdin/stdout duplicates. If program want's to read
sees that it's stdin was closed it terminates the network
connection.
OPTIONS
The following command line options are available:
-a [interface]:[port]
tells connect to bind to the specified port on the
given interface and to wait for a client to connect
instead of connecting to the remote end on it's
own.
-l [interface]:[port]
uses interface and port as local connection end-
point in client mode.
-p sets `program pipe mode' in client or FTP-DATA
mode: after the network connect is established the
program that is given by the remaining command line
arguments is started and it's stdin and stdout is
connected to the connection's remote end.
-r filename
read connection data from filename instead from
stdin.
-s sets server mode, see above.
-t timeout
sets the connection timeout in seconds. If for
timeout seconds nothing happens on the connection
it will be terminated. The default is 60 seconds.
-w filename
write connection data to filename instead to std-
out.
-v prefix
change the common variable prefix CONNECT_ to pre-
fix.
-x print local and remote endpoint information after
the connection is established.
Notice that options may be mutually exclusive (e.g. -s and
-p). connect does not competly check if all given option
can be used together or not. If e.g the -l option is set
together with -s it's silently ignored.
SEE ALSO
gawk(1)