.\" As its sole author, I explicitly place this file in the public domain.
.\" It may be used by anyone in any way for any purpose, though I would
.\" appreciate credit where it's due.
.\"		der Mouse, mouse@rodents.montreal.qc.ca, 1999-09-04
.Dd April 3, 2006
.Dt NC 1
.Os NetBSD 1.4T
.Sh NAME
.Nm nc
.Nd network connection utility
.Sh SYNOPSIS
.Nm
.Op Fl stdin
.Op Fl net
.Op Fl holdstdin
.Op Fl holdnet
.Op Fl timestdin Ar t
.Op Fl timenet Ar t
.Op Fl ra
.Op Fl rp
.Op Fl ka
.Op Fl nd
.Op Fl 4
.Op Fl 6
.Op Fl any
.Op Fl retry
.Op Fl reblock
.Op Fl cmd Ar cmd
.Op Fl server Ar cmd
.Op Fl server1 Ar cmd
.Op Fl src Ar arg
.Op Fl lockstep Ar nb
.Oo
.Fl src
.Oo Ar host Oc Ns Xo
.Op / Ns Op Ar port
.Xc
.Oc
.Op Ar host
.Ar port
.Sh DESCRIPTION
.Nm
is a small tool designed for making TCP connections.  With two
arguments, it establishes a connection to the specified
.Ar host
on the specified
.Ar port ;
with only one argument, it listens on the specified
.Ar port
for an incoming connection.  In either case, once the connection is
established, it simply copies bytes from its standard input to the
connection, and from the connection to its standard output.  If it
reads EOF on its stdin, it will close down the transmit side of its
connection; if it sees the receive side of the connection close, it
will use
.Xr shutdown 2
to indicate
.Dq no more sends
on its own stdout, or, if that fails (for example, because stdout is
not a socket or pipe), it will close its stdout.
.Pp
Flags understood:
.Bl -tag -width indent
.It Fl stdin
Don't wait for EOF on stdin in order to exit.
.It Fl net
Don't wait for EOF on the network connection in order to exit.
.It Fl holdstdin
Upon reading EOF from stdin, don't shut down the network connection
(but otherwise act on the EOF as normal).
.It Fl holdnet
Upon reading EOF from the network connection, don't shut down or close
stdout (but otherwise act on the EOF as normal).
.It Fl timestdin Ar t
If ever
.Ar t
seconds go by without any input being received from stdin, treat it as
if EOF had been read on stdin.  A value of 0 indicates
.Sq no timeout .
.It Fl timenet Ar t
If ever
.Ar t
seconds go by without any input being received from the network
connection, treat it as if EOF had been read on the network connection.
A value of 0 indicates
.Sq no timeout .
.It Fl ra
Turn on
.Dv SO_REUSEADDR
on the socket (see
.Xr setsockopt 2 ) .
.It Fl rp
Turn on
.Dv SO_REUSEPORT
on the socket (see
.Xr setsockopt 2 ) .
.It Fl ka
Turn on keepalives (the
.Dv SO_KEEPALIVE
option, see
.Xr setsockopt 2 )
on the connection.
.It Fl nd
Turn on the
.Dv TCP_NODELAY
option (see
.Xr setsockopt 2 )
on the connection.
.It Fl 4
Specifies that IPv4 may be used (see below).
.It Fl 6
Specifies that IPv6 may be used (see below).
.It Fl any
Specifies that any protocol may be used (see below).
.It Fl retry
Specifies that if a connection attempt fails, rather than the usual
action (printing an error and exiting),
.Nm
is to sleep briefly and retry.  There is no limit placed on retries; if
the connection never succeeds,
.Nm
will loop forever retrying.  This option makes sense only when
.Nm
is initiating a connection (it is not an error in other circumstances,
but it will have no effect).
.It Fl reblock
Specifies that the data streams are to be randomly re-blocked.  That
is,
.Nm
attempts to disrupt packet boundaries, by collapsing data blocks
received in quick succession and by delaying portions of data blocks
slightly.  This is intended to help debug network protocol
implementation bugs that show up only when network packet boundaries do
not match up with
.Sq natural
boundaries for the higher-level protocol.  (TCP has never guaranteed
preservation of such boundaries, but it does so surprisingly often
anyway, which makes it difficult to reproduce such bugs and thereby
debug them.)  Data will be delayed no more than slightly by this
option.
.Pp
This option does not work in conjunction with
.Fl cmd ,
.Fl server ,
or
.Fl server1 ,
since in those cases
.Nm
does not handle the data at all.
.It Fl cmd Ar cmd
.Nm
does no I/O or data copying.  Instead, once the network connection is
set up,
.Nm
simply execs
.Ar cmd
(which must be a single argument, and is passed to
.Dv \&$SHELL
with the
.Fl c
convention), with the network connection on standard input and output.
.It Fl server Ar cmd
This is just like
.Fl cmd ,
except that for each incoming connection, a new process is forked to
execute
.Ar cmd
and the original process continues listening and accepting connections.
This option thus produces a
.Sq network server
mode of operation.
.Fl server
is incompatible with specifying the
.Ar host
argument; it is permitted only when
.Nm
is accepting connections.
.It Fl server1 Ar cmd
Like
.Fl server ,
.Fl server1
also causes
.Nm
to run as a network server.  The difference is that with
.Fl server1 ,
the server is
.Sq single-threaded .
That is, when a connection is accepted and the handler process forked,
no further accepts will be done until the
.Ar cmd
exits.  Like
.Fl server ,
.Fl server1
is incompatible with specifying the
.Ar host
argument; it is permitted only when
.Nm
is accepting connections.
.It Fl src Xo
.Oo Ar host Oc Ns Xo
.Op / Ns Op Ar port
.Xc
.Xc
Specifies that the local address of the connection should be address
.Ar host
port
.Ar port ,
except that when no
.Ar host
argument is given (ie,
.Nm
is doing a passive-listen connection), the
.Ar port
argument on the command line overrides any port number specified here.
The default for the
.Ar host
portion is
.Dv INADDR_ANY ;
the default for the
.Ar port
portion is 0, which requests that the kernel select a free port.
.It Fl lockstep Ar nb
Instead of simply copying data, implement a very simple packetizing
protocol which never sends more than
.Ar nb
bytes of data without getting an acknowledgement back from the peer.
This is intended to work around various network bugs (for example, if
path MTU discovery is broken, you can use this with a value somewhat
smaller than your path MTU to allow transfers despite the MTU issues).
The packetizing protocol is run in both directions.  It is not
documented here; see the source code.
.Pp
Note that
.Fl lockstep
must be given on both ends, or the protocol will not work.  However,
.Ar nb
does not need to be the same in both directions.  The value given to a
process applies to data written by that process.
.El
.Pp
.Nm
is useful when you have shells on two machines and want to move data
betwen them, but don't want to (or can't) set up rsh-style trust
between them.  For example, if you have
.Pa foo.c
on machine-A and want to move it to machine-B, you might do
.\" Grr, why does .Bd/.Ed produce a blank line before but not after?!
.Bd -literal -offset indent
machine-A% nc 12345 < foo.c
machine-B% nc -stdin machine-A 12345 > foo.c

.Ed
(Note the
.Fl stdin ;
without this, you would have to redirect stdin from /dev/null, or type
an EOF, on machine-B, in order for
.Nm
to exit.)
.Pp
.Nm
is also useful to connect to some types of network services; for
example, you can often fetch a web page with a command such as
.Dl % echo GET /page.html | nc www.site.edu http > some-file
though many web servers are broken in various ways that hamper the
usefulness of this technique.
.Pp
By default,
.Nm
is willing to use any protocol it knows about.  If any of the
protocol-specification flags are given, such as
.Fl 4 ,
then it restricts itself to the listed protocols.  These options
accumulate, so that if (for example)
.Fl 4
and
.Fl 6
are given,
.Nm
is willing to use IPv4 or IPv6, but no others.
.Fl any
restores the default state, which is to use any protocol unless further
protocol-specification flags are given.
.Sh AUTHOR
der Mouse,
.Aq mouse@rodents.montreal.qc.ca .