NAME
accept, connect, filehandler, shutdown - Opens and handles TCP connections

accept file
    Accepts a connection on an existing server file (created with the connect command) and returns an identifier with may be used in commands like read, write and close. If the listening socket is a INET domain socket, the remote machine IP address and remote port number of the connection are stored as a list in the global array connect_info in the element referenced by the identifier returned from accept. If the socket is a UNIX domain socket, then an empty string is stored in the array connect_info.

connect ["-server"] host port
    Connects to or sets up an INET server with TCP and returns an identifier that may be used in future invocations of commands. If "-server" is specified then a listening socket is set up. If host is a non-empty string, this specifies the remote address in the same way as bind(2) does. If host is an empty string, then any machine may connect. If port is empty or 0, then the system will select a port number for you. The returned identifier may be used in commands like accept, close and filehandler. The port number of the connection is saved in the global array connect_info in the element with the same name as the returned identifier. You may only use the returned identifier in the close, accept and filehandler commands. If "-server" is not specified, then a connection is made to a remote server. The returned identifier may be used in commands like read, write, gets, puts and close. host gives the name of the host to connect to. port gives the desired port. Even if every socket is opened for both reading and writing, seek must not be invoked between a read and a write.

connect ["-server"] path
    Set up a UNIX domain socket. This command is identical to the one above except that a UNIX domain socket is created with an address specified by path. An empty string is stored in the global array connect_info.

shutdown file code
    Shutdown a connection for reading, writing or both. If code is "0", "read" or "receives" then further receives on file will be disabled. If code is "1", "write" or "sends", then further sends on file will be disabled (and eof will be sent on the socket). If code is "2", "all" or "both", then further reads and writes on file will be disabled.

filehandler file ?mode command?
    The filehander command is only used with Tk. The command specifies a TCL command to be called whenever the given file can be read, written, and/or when there is an exeptional condition. The mode argument indicates the situations when the command will be called. It may be any combination of the following values:

    r   Call command whenever the there is data to read from the socket. The command procedure is called with two arguemnts: r to indicate that there is something to read, and a file id that can be used for reading. The procedure should read at least some data from the socket, or otherwise the procedure will be called continuously.

    w   Call command whenever data can be written to the socket. This option is rarely used since most sockets can be written most of the time.

    e   Call command whenever there is an exceptional condition pending on the socket. The command procedure is called with two arguments: an e to indicate exception, and a file id that can be used as an argument to read, close etc.

    The same command may be used for several different conditions. The first argument supplied to command denotes always the condition type. If there are several different conditions (e.g. the file can be both read and written), the command will be called separately for each condition. Specifying a new command with filehandler will remove any earlier command from use. NOTE! Currently there is a small memory leak whenever a new command replaces an existing one. When a command procedure is specified for the socket via filehandler command, the socket will be automatically closed and the associated file handler deleted if there is a pending eof or error condition after executing the user supplied command procedure.

AUTHOR
Pekka Nikander, Telecom Finland (Pekka.Nikander@ajk.tele.fi) Extended by Tim MacKenzie (tym@dibbler.cs.monash.edu.au)