gpm: Open and Close
4.2.2 Connecting and Disconnecting
----------------------------------
-- Function: int Gpm_Open (Gpm_Connect *CONN, int FLAG);
Open a connection with the server. The CONN parameter points to
the connection information for the being-created connection, as
already described. Connection Details. It is passed to
the server after filling the 'pid' and 'vc' fields.
FLAG should be '0' for normal applications, those interested in
events related to their own console. The own console is considered
to be the one attached to 'stdin', and it must match the string
'/dev/tty*'. A negative value for FLAG is used to make the
invoking application a default handler Default Handlers,
while a positive value is used to force connection to a particular
console, either for debugging issues or whenever 'stdin' is not a
tty when 'Gpm_Open' is invoked.
Multiple opens are allowed, and a stack of 'Gpm_Connect' structures
is managed by the library. You can, thus, re-open the connection
in order to temporarily change the range of events you're
interested in. When you invoke an external program, for example,
you should re-open the connection with 'eventMask' zeroed, and
'defaultMask', 'minMod' and 'maxMod' all equal to '~0'.
The return value is either '-1' or the file descriptor used to
communicate with the server. When run under xterm, a gpm client
gets event through 'stdin', and the return value for 'Gpm_Open()'
will be '-2'. This value is always available in 'gpm_fd'.
-- Function: int Gpm_Close (void);
Pops the connection stack. It is used to restore the previous
situation after a change in the connection masks. Closes the
actual connection when the stack gets empty. On last close it
returns 0, -1 otherwise.