# $EPIC: connect,v 1.7 2004/04/09 17:37:47 brian Exp $
Synopsis:
   $connect(<host> <port> [family])

Technical:
   * If the <host> argument is omitted the empty string is returned.
   * If the <port> argument is omitted the empty string is returned.
   * If the <host> argument does not resolve to a known Internet hostname,
     an error is output and the empty string is returned.
   * If a TCP connection to host <host> on port <port> cannot be opened,
     an error is output and the empty string is returned.
   * If the connection is established, then:
		/ON DCC_RAW "<fd> <host> E <port>"
     will be thrown before this function returns.  <fd> is an integer
     by which you can refer to this connection with /dcc raw and /msg.
   * The return value of this function is a small integer suitable for
     use with /DCC RAW and /MSG.
   * The optional [family] argument can be 4, 6, v4, or v6 to specify
     usage of IPv4 or IPv6.

Practical:
   This function will let you open up a TCP socket to any host/port.  You
   can send messages to the connection using the return value as the key 
   argument to DCC RAW and MSG.  You will receive messages from the 
   connection via /ON DCC_RAW "<fd> <host> D <data>".

Returns:
   A number to be used for communication with an open TCP connection,
   or the empty string if an error occurs.

Examples:
   A complete example of opening up a connection to the local SMTPd,
   sending a command, receiving responses, and cleaning up afterwards.

	alias mailcheck 
	{
		@ :host = [127.0.0.1]
		@ :port = 25

		on ^dcc_raw "% $host D *" {
			echo -- Incoming! -- $2-
		}
		on ^dcc_lost "% RAW $host" {
			on dcc_raw -"% $2 D"
			on dcc_lost -$*
		}

		@ :fd = connect($host $port)
		msg =$fd QUIT
	}

History:
   This function first appeared in ircII-2.2pre3

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

