.\" $NetBSD: nc.1,v 1.3 2004/02/01 00:17:17 snj Exp $
.Dd October 1, 1999
.Dt NC 1
.Sh NAME
.Nm nc (netcat)
.Nd use network sockets from the command line
.Sh SYNOPSIS
.Nm
.Op Fl h
.Nm ""
.Op Fl ruvz
.Op Fl g Ar gateway
.Op Fl G Ar num
.Op Fl i Ar secs
.Op Fl p Ar port
.Op Fl o Ar file
.Op Fl s Ar addr
.Op Fl w Ar secs
.Ar hostname port[s] [ports] ...
.Ek
.Nm ""
.Ar -l
.Ar -p port
.Op Fl nsuvwz
.Op Fl o Ar file
.Ar [hostname] [port]
.\" ae:g:G:hi:lno:p:rs:tuvw:z
.\"connect to somewhere:   nc [-options] hostname port[s] [ports] ...
.\"listen for inbound:     nc -l -p port [-options] [hostname] [port]
.\"options:
.\"        -g gateway              source-routing hop point[s], up to 8
.\"        -G num                  source-routing pointer: 4, 8, 12, ...
.\"        -h                      this cruft
.\"        -i secs                 delay interval for lines sent, ports scanned
.\"        -l                      listen mode, for inbound connects
.\"        -n                      numeric-only IP addresses, no DNS
.\"        -o file                 hex dump of traffic
.\"        -p port                 local port number
.\"        -r                      randomize local and remote ports
.\"        -s addr                 local source address
.\"        -u                      UDP mode
.\"        -v                      verbose [use twice to be more verbose]
.\"        -w secs                 timeout for connects and final net reads
.\"        -z                      zero-I/O mode [used for scanning]
.\"port numbers can be individual or ranges: lo-hi [inclusive]
.Sh DESCRIPTION
.Nm
allows you to use network sockets (tcp or udp) from the shell.  I'm
merely writing this man page so that i can "man nc" and find out
what I've already forgotten.
.Pp
For connecting to remote sites, it's usually only necessary to supply the
.Ar host
or
.Ar ip address
and
.Ar port
for the connection.  For a listening on a socket, you must specify
.Ar -l
for listening, and
.Ar -p port
to specify the port on which you want to listen.
.Pp
The options are as follows (with C and S indicating whether the option
applies to the "client" or "server" roles in a tcp conversation):
.Bl -tag -width Ds
.It Fl g Ar gateway (C)
Specifies a source routing hop for outbound connections.
.It Fl G Ar num (C)
Can be used to specify the source routing pointer in the ip header,
presumably in order to forge unused previous steps in the source
routed path.
.It Fl h
Minor help.  Not very helpful, hence this man page.
.It Fl i Ar secs (C)
Delay interval for lines sent or ports scanned.
.It Fl l Ar (S)
Selects "listen" mode instead of connect mode so that people
can connect to you.
.It Fl n Ar (S)
The
.Fl n
option indicates that all ip addresses should be printed out instead
of being looked up in the DNS.
.It Fl o Ar file (CS)
Sends a hex-dump of the traffic to the specified file.
.It Fl p Ar local port number (CS)
When connecting to a remote service, this is the port from which the
connection will originate.  When listening for remote clients, this
specifies the local port on which to listen.
.It Fl r Ar (C)
Randomizes local source ports and addresses for outbound connections.
.It Fl s Ar source address (CS)
Specifies the local source address on which to listen, or from which
to connect.
.It Fl u Ar (CS)
Selects UDP transport as opposed to TCP (the default).
.It Fl v Ar (CS)
Turns on verbosity.  Use two (or more) for more verbosity.
.It Fl w Ar secs (CS)
This sets a timeout for connects or for final net reads.
.It Fl z Ar (CS)
Zero I/O mode.  While mostly used for scanning, I'm sure you could find
a way to use it for connect mode.
.El
.Pp
The
.Nm
utility exits after both input streams (stdin and the remote socket)
have been closed.  It doesn't do this very well, and relies rather
heavily on the network layers at both ends for this, and as such, if
microsoft products are used, it might not notice a close because microsoft
sucks.
.Sh SEE ALSO
.Xr cat 1
.Sh HISTORY
The
.Nm
utility, a "damn useful little backend utility" begun 950915 or thereabouts,
as *Hobbit*'s first real stab at some sockets programming.  Something that
should have and indeed may have existed ten years ago, but never became a
standard Unix utility.  IMHO,
.Nm
could take its place right next to cat,
cp, rm, mv, dd, ls, and all those other cryptic and Unix-like things.
.Sh BUGS
I don't know...I didn't write the damn thing.  But there are probably
a bunch.  Go blame microsoft.