/connect

Usage:

/CONNECT [-lqxbf] [world]
/CONNECT host port

In the first form, /connect attempts to open a socket connected to world. World must be defined by the /addworld command and not already open. If world is omitted, the first defined world will be used. If world does not have a host and port, /connect will create a "connectionless" socket. In the form "/connect host port", it will define a temporary world named "(unnamedN)" with the given address, and try to connect to it. Host may be an internet hostname, an IPv4 address, or (if your platform supports it) an IPv6 address. A temporary world will be undefined when it is no longer in use.

Options:

-l

No automatic login (i.e., don't call the LOGIN hook).

-q

Quiet login (overrides %{quiet} flag).

-x

Connect using SSL (not necessary if world was defined with the "x" flag).

-f

Connect in the foreground

-b

Connect in the background

The first thing /connect does is create a new socket. If the -f option was given, or /connect was called from the foreground (e.g., from the command line), the new socket is immediately brought into the foreground. If the -b option was given, or /connect was called from the background (e.g., from a DISCONNECT hook in a background world), the connection proceeds in the background.

If a hostname was given, TF must look it up to find one or more IPv4 or (if your platform supports it) IPv6 addresses. If %{gethostbyname} is "nonblocking" (the default), and this process takes more than a fraction of a second, TF will print "Hostname resolution for world in progress" (the PENDING hook), and TF will continue running normally while the lookup proceeds. But if %{gethostbyname} is "blocking", TF will freeze until the lookup is finished. Either way, if the lookup succeeds, TF will try to connect; if it fails, you will be notified.

Next, TF tries to open a network connection to the IP address, and prints "Trying to connect to world: address port" (the PENDING hook). On most platforms, if %{connect} is "nonblocking" (the default), TF continues running normally while the network connection proceeds. But if %{connect} is "blocking", TF will freeze until the network connection is finished. If the connection succeeds, a message is printed, but (unlike previous versions of TF) the socket is not automatically brought to the foreground. However, if you had run /connect in the foreground (e.g. from the command line), the socket would already be in the foreground, unless it was nonblocking and had taken a long time and you foregrounded another socket while you were waiting, in which case you probably wouldn't want to automatically foreground the new socket. If you prefer automatic foregrounding upon successful connection, you can define a CONNECT hook that calls "/fg %{1}".

Even if %{gethostbyname} and/or %{connect} are "blocking", they can be interrupted with the SIGINT signal (^C).

If the connection fails, TF normally prints "Connection to world failed: address port: reason" (the CONFAIL hook). But, if the failure was in the specific address, and there is more than one address associated with the world's hostname, the message will instead say "Intermediate connection to world failed: ..." (the ICONFAIL hook), and TF will try to connect to the next address. So, a failed /connect will always result in a series of zero or more ICONFAIL hooks followed by exactly one CONFAIL hook. But an ICONFAIL may also be followed by a successful connection to an alternate address.

If the network connection is successful, or the socket is "connectionless", these events occur:

• If the world was defined with an mfile, that file will be loaded (and the LOAD hook will be called);
• The CONNECT hook is called (unless the socket is connectionless or the connection is via a proxy).
• If %{login} is on, and a character and password is defined for the world, the LOGIN hook is called (unless the socket is connectionless or the connection is via a proxy). The default LOGIN hooks sends the character name and password in a format corresponding to the world type. To automatically login to a world that expects a different login format, define your own LOGIN hook.

If you have trouble connecting (especially if you use SOCKS), try "/set connect=blocking".

If your host has multiple network interfaces, the OS will choose one of them for the client end of the connection according to its own rules. To override the system's choice, set the tfhost variable or define the world with a srchost parameter to addworld.

/connect returns 0 on error or failure, 1 for immediate success, or 2 if the name lookup or network connection is pending.

See: worlds, sockets, proxy, /world, /addworld, /fg, /retry, %login, %gethostbyname, %connect, hooks procotols