# $EPIC: listen,v 1.6 2002/09/27 00:43:00 dinodrac Exp $
Synopsis:
   $listen()
   $listen(<port> [family])

Technical:
   * The listen function establishes a passive TCP connection (``server'').
   * The <port> argument is optional and if provided is taken as a number.
   * If the <port> argument is not a number, the empty string is returned.
   * If the <port> argument is not zero and less than 1024, the empty string 
     is returned.
   * The optional family argument can be 4, 6, v4, or v6, and tells the
     client whether it should bind to IPv4 or IPv6.
   * If the requested port is not available (probably because it is in use
     by someone else), an error is output and the empty string is returned.
   * The return value is the local port number associated with the connection.

Practical:
   If you want your script to act as an Internet server, the $listen() function
   lets you establish a place where others can $connect() to you.  Once they
   $connect() to you, you are given a small integer that acts in the same way
   that $connect() return values do.

Returns:
   The port number being listened on, or the empty string on error.

Examples:
   $listen(1025)             returns 1025
   $listen(1023)             error, returns nothing
   $listen(0)                returns a system-allocated port number
   $listen()                 returns a system-allocated port number

History:
   This function first appeared in ircII-2.2pre3

See Also:
   connect(6); dcc(1) close, raw; on(5) dcc_raw