gtk-server.1

gtk_server的源代码

.TH gtk\-server 1
.SH "NAME"
gtk\-server \- GUI access for shellscripts and interpreted languages.
.SH "SYNOPSIS" 
.B gtk\-server
.I <\-stdin> |
.I <\-tcp>=host:port[:max] |
.I <\-sock>=host:port |
.I <\-udp>=host:port |
.I <\-fifo>=filename |
.I <\-ipc>=number
.I [\-log=filename]
.I [\-signal=number]
.I [\-cfg=filename]
.I [\-pre=string]
.I [\-post=string]
.I [\-handle]
.I [\-detach]
.I [\-nocreate]
.I [\-showconf]
.I [\-start=macro]
.I [\-init=handshake]
.I [\-ssl=[cert.pem]]
.I [\-password=passwd]
.I [\-ca=cert.pem]
.SH "DESCRIPTION"
.P
The GTK\-server is a binary which can be started from a (shell\-)script or
an interpreted language. 
It will read the configuration file 'gtk\-server.cfg' after which a 
client script can execute GTK functions. These GTK functions are sent in
plain text to the gtk\-server, using a 2\-way pipe, a named pipe or a TCP or UDP
connection.
.P
The GTK\-server was inspired by 'dtksh' for the Common Desktop
Environment (CDE).
.SH "ARGUMENTS"
.PP
The GTK\-server must be started with one of the following
arguments:
.TP
.B -stdin
Start the GTK\-server with 2\-way pipes. The client script language must start
a 2\-way pipe to the GTK\-server to enable communication. (In KSH and AWK for example, the 
symbol '|&' is used for this.)
.TP
.B -tcp=host:port[:max]
Start the GTK\-server as TCP server. The client script language must
connect to this host and port. Commonly 'localhost' and a portnumber higher than 
1024 are used. The 'max' part determines the maximum amount of client scripts 
which can connect. If 'max' is omitted only 1 client script may connect.
.TP
.B -sock=host:port
Start the GTK\-server as TCP client. The client script language acts like a server, sending
the commands to the GTK-server.
.TP
.B -udp=host:port
Start the GTK-server in UDP mode. The client script must connect to <host> and 
<port> using the UDP protocol.
.TP
.B -fifo=<file>
Start the GTK\-server with a named pipe. The pipe is created by the GTK\-server automatically
and has the name of <file>. When the script is finished the named pipe will be
deleted automatically. To avoid the pipe being created automatically, also use the option 'nocreate'.
.TP
.B -ipc=number
Start the GTK\-server with a message queue. The number must lay within the range from
1 to 65535 and specifies the queue number. When the script is finished the GTK\-server will
delete the message queue from memory.
.br

After the GTK\-server has been started with a message queue, subsequent GTK requests must
be sent with the GTK\-server binary using the argument 'msg'. The number of the communication
channel must be specified, as well as the string to be sent. For example:
.br

.B gtk-server -msg=1,"gtk_init NULL NULL"
.br

Here a GTK function is sent to communication channel 1. Make sure there is no space between
the number, the comma and the string, otherwise the GTK-server will regard these as separate
arguments.
.br

Message queues also can be retrieved using the Unix command 'ipcs', and can be deleted using
the Unix command 'ipcrm'.
.br

.SH "OPTIONS"
.PP
The GTK\-server accepts the following optional parameters:
.TP
.B -log=<filename>
Start the GTK\-server in debug mode. A file with the name 'filename' will be created. This logfile 
contains the strings which were received by the GTK\-server, and the responses
of the GTK\-server to those strings.
.TP
.B -signal=<number>
Define a signal which must be sent to the clientprogram when the GTK-server exits (UNIX only).
.TP
.B -cfg=<filename>
Explain to the GTK-server where it can find the configfile if it cannot be found at a standard
location.
.TP
.B -pre=<string>
Put the specified string in front of the GTK-server returnstrings.
.TP
.B -post=<string>
Put the specified string behind the GTK-server returnstrings.
.TP
.B -nocreate
To be used in combination with the fifo option. When specified the pipefile will not be created
by the GTK\-server, but must be created by the client program.
.TP
.B -handle
This option can be used to synchronize communication. When specified the client script can send requests
starting with a self-defined handle, for example a unique number. The GTK\-server will ignore this
handle when parsing the incoming request, but the returnstring for this request will start with the same handle.
.TP
.B -detach
When specified the GTK\-server will try to spawn to the background.
.TP
.B -showconf
When the GTK-server starts, it will read information about GTK-calls from the configfile.
This argument will dump the information to stdout. This is particularly usefull when
debugging scripts.
.TP
.B -start=<macro>
When the GTK-server starts, first execute the specified macro before doing anything else.
.TP
.B -init=<handshake>
When running in socket mode, the GTK-server can send a string to handshake and identify itself with
the other side.
.TP
.B -ssl[=cert.pem]
When running in socket mode, this option sets up an SSL connection. An optional certificatefile
can be provided which is presented by the GTK\-server to the remote host during the SSL negotiation.
.TP
.B -ca=cert.pem
When running in socket mode, this option sets up an SSL connection. A certificatefile must be
provided to this option to verify the certificate presented by the remote host.
.TP
.B -password=string
To be used in combination with the ssl option. This option should provide a password to decrypt
the SSL certificate's key if the key was encrypted.

.SH "SHEBANG"
.PP
A GTK-server configfile can contain a standalone program implemented with macro's. As with most Unix
scripts, a shebang can be added to the first line of the configfile to execute it with the GTK-server:
.P
.B
#!/usr/bin/gtk-server -this
.P
The GTK-server searches for a macro with the name 'main' which will be executed first.

.SH "SHARED OBJECT / DLL / MODULE"
.PP
If the GTK-server is compiled as a shared object, the function 'gtk' can be imported
into the client program. All GTK calls can be passed as a stringargument to this function
(formatted as S-expression). The function always will return a pointer to a string containing
the result of the last GTK call.
.P
The C-prototype definition for the 'gtk' function in the GTK-server is as follows:
.P
.B
(char*) gtk (char* S-expression)
.P
It is also possible to compile the GTK-server as an S-Lang, Scriptbasic or Kornshell module,
which can be imported in a client program. See the respective directories in the sourcepackage
for details.
.P
Only with the first call to the imported 'gtk'-function the options 'log', 'cfg', 'pre' and 'post' can be
submitted. For example:
.P
gtk "log=/dir/logfile cfg=/my/dir/gtk-server.cfg post=."
.P
Now the GTK-server module will open the configfile at location '/my/dir', output it's logging
to the configured logfile and also will put a dot behind all returned answers. (These separate options
also may be preceded by the dummy command 'gtk_server_cfg'.)

.SH "INTERNAL COMMANDS"
.PP
The GTK-server recognizes the following internal commands:
.TP
.B gtk_server_version
This command returns the current version of the GTK-server.
.TP
.B gtk_server_ffi
This command returns the Foreign Function interface which has been used to compile the GTK-server: FFI,
FFCALL, C/Invoke or DYNCALL.
.TP
.B gtk_server_toolkit
This command returns the backend which has been used to compile the GTK-server: GTK1, GTK2 or XForms.
.TP
.B gtk_server_os
This command returns the platform for which the GTK-server was compiled.
.TP
.B gtk_server_callback <argument>
With this command the client program will fetch a signal for one of the widgets.
By default the widget ID is returned when a signal is received. If <argument> is 0,
the command will return to the client program immediately, and the client program
has to perform a GTK iteration by itself. If there was no signal, the returnvalue will
be 0. If <argument> is 1, the command also will