aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorMattias Andrée <maandree@operamail.com>2015-07-07 07:14:34 +0200
committerMattias Andrée <maandree@operamail.com>2015-07-07 07:14:34 +0200
commit5b29ad8d7b5b33b86a58077f0d98cef1bb65b0a5 (patch)
tree610cbc93f68eef0d39d8c877ac58377e5534497f /doc
parentindicies (diff)
downloadmds-5b29ad8d7b5b33b86a58077f0d98cef1bb65b0a5.tar.gz
mds-5b29ad8d7b5b33b86a58077f0d98cef1bb65b0a5.tar.bz2
mds-5b29ad8d7b5b33b86a58077f0d98cef1bb65b0a5.tar.xz
indicies
Signed-off-by: Mattias Andrée <maandree@operamail.com>
Diffstat (limited to '')
-rw-r--r--doc/info/mds.texinfo290
1 files changed, 192 insertions, 98 deletions
diff --git a/doc/info/mds.texinfo b/doc/info/mds.texinfo
index 05ec173..48c138d 100644
--- a/doc/info/mds.texinfo
+++ b/doc/info/mds.texinfo
@@ -131,7 +131,7 @@ Rather than one, possibly modular, process --- a monolithic
process --- @code{mds} is comprised of many small servers,
each exchangable and responsible for one thing.
-@cpindex{Goals of @command{mds}}
+@cindex Goals of @command{mds}
@command{mds}'s goal is neither security, performance nor
a perfect graphical experience. @command{mds} is all
about flexibility and freedom 0@footnote{The freedom to run
@@ -198,10 +198,10 @@ of crashing.
@node Layers
@section Layers
-@cpindex{Layers, architecture}
-@cpindex{Architectural layers}
-@cpindex{Kernel}
-@cpindex{Master server}
+@cpindex Layers, architecture
+@cpindex Architectural layers
+@cpindex Kernel
+@cpindex Master server
The @command{mds} display server in architectured in
three layers. The first layer is called the kernel.
The kernel is responsible for acquiring a display
@@ -218,10 +218,10 @@ the domain socket for communication with the display
server, it is not responsible for using it, that
mission falls to the master server.
-@cpindex{Master server}
-@cpindex{Message passing, coordination}
-@cpindex{Communication, coordination}
-@cpindex{Interprocess communication, coordination}
+@cpindex Master server
+@cpindex Message passing, coordination
+@cpindex Communication, coordination
+@cpindex Interprocess communication, coordination
The second layer is the master server. The master
server has two responsibilities: coordinating
message passing between other servers and clients
@@ -230,9 +230,9 @@ distinction between servers and clients, the
distinction is purely semantic.} and starting
other servers.
-@cpindex{Starting of servers}
-@cpindex{Servers, starting}
-@pgindex{@file{mdsinitrc}}
+@cpindex Starting of servers
+@cpindex Servers, starting
+@pgindex @file{mdsinitrc}
The third layer is the other servers and clients.
protocolwise there is no specification on how
they are started. But in the reference
@@ -254,10 +254,10 @@ of the display server.
@node Interprocess Communication
@section Interprocess Communication
-@cpindex{Message passing, mechanism}
-@cpindex{Communication, mechanism}
-@cpindex{Interprocess communication, mechanism}
-@cpindex{Master server}
+@cpindex Message passing, mechanism
+@cpindex Communication, mechanism
+@cpindex Interprocess communication, mechanism
+@cpindex Master server
Intrinsic to @command{mds} is a powerful
interprocess communication mechanism. Servers
and clients connect to the display server by
@@ -277,12 +277,12 @@ Multicast a message.
Join or leave a multicast group.
@end itemize
-@cpindex{Multicast groups}
-@cpindex{Client ID assignment}
-@cpindex{ID assignment}
-@cpindex{Assignment of ID}
-@cpindex{Disconnection}
-@cpindex{Master server}
+@cpindex Multicast groups
+@cpindex Client ID assignment
+@cpindex ID assignment
+@cpindex Assignment of ID
+@cpindex Disconnection
+@cpindex Master server
Upon assignment of an ID the master server
will automatically place the client in a
multicast group for that specific client.
@@ -293,11 +293,11 @@ a client is disconnected it will send out a
message to a specific multicast group that
the client, refered to by it's ID, have closed.
-@cpindex{Message passing, message structure}
-@cpindex{Communication, message structure}
-@cpindex{Interprocess communication, message structure}
-@cpindex{Message structure, message passing}
-@cpindex{Master server}
+@cpindex Message passing, message structure
+@cpindex Communication, message structure
+@cpindex Interprocess communication, message structure
+@cpindex Message structure, message passing
+@cpindex Master server
A message in the @command{mds} protocol is
comprised of two parts: headers and a payload.
When a client joins a multicast group it is
@@ -309,13 +309,13 @@ could be used for logging, possibly spying and
networking.}. Thus a message is automatically
multicasted to groups indicated by its headers.
-@cpindex{Interceptions, message passing}
-@cpindex{Message passing, message modification}
-@cpindex{Communication, message modification}
-@cpindex{Interprocess communication, message modification}
-@cpindex{Message modification, message passing}
-@cpindex{Master server}
-@cpindex{Multicast groups}
+@cpindex Interceptions, message passing
+@cpindex Message passing, message modification
+@cpindex Communication, message modification
+@cpindex Interprocess communication, message modification
+@cpindex Message modification, message passing
+@cpindex Master server
+@cpindex Multicast groups
The multicast groups and receiving of message
is called interceptions. The interesting
property of interceptions is that they may
@@ -336,10 +336,10 @@ the message to make it empty. A consumed
message will not be send to any further
clients or servers in the interception list.
-@cpindex{Interception priority, message passing}
-@cpindex{Priority, interception, message passing}
-@cpindex{Message consumption, message passing}
-@cpindex{Consumption, interception, message passing}
+@cpindex Interception priority, message passing
+@cpindex Priority, interception, message passing
+@cpindex Message consumption, message passing
+@cpindex Consumption, interception, message passing
To make this mechanism sensible, a server or
client can set a priority when it registers
for interception (does not need to be
@@ -358,14 +358,14 @@ same priority the order in which they will
receive the message, of those recipients,
is arbitrary.
-@pgindex{@command{mds-vt}}
-@cpindex{Virtual terminal, switching}
-@cpindex{Switching virtual terminal}
-@cpindex{Dual-connection, message passing}
-@cpindex{Message passing, dual-connection}
-@cpindex{Communication, dual-connection}
-@cpindex{Interprocess communication, dual-connection}
-@cpindex{Reflexive connection, message passing}
+@pgindex @command{mds-vt}
+@cpindex Virtual terminal, switching
+@cpindex Switching virtual terminal
+@cpindex Dual-connection, message passing
+@cpindex Message passing, dual-connection
+@cpindex Communication, dual-connection
+@cpindex Interprocess communication, dual-connection
+@cpindex Reflexive connection, message passing
An interesting property of this mechanism
is demonstrated in the @command{mds-vt}
server. Unlike most servers @command{mds-vt}
@@ -399,18 +399,18 @@ and wait for a reply from all of them.
@node Application Design
@chapter Application Design
-@cpindex{Application design}
-@cpindex{Client design}
-@cpindex{Guildlines, applications}
-@cpindex{Toolkit guildlines}
+@cpindex Application design
+@cpindex Client design
+@cpindex Guildlines, applications
+@cpindex Toolkit guildlines
When creating graphical @command{mds} applications,
there are some guildlines you should follow.
@itemize @bullet
@item
-@cpindex{Client-side decoration}
-@cpindex{Server-side decoration}
-@cpindex{Decoration, guildlines}
+@cpindex Client-side decoration
+@cpindex Server-side decoration
+@cpindex Decoration, guildlines
@b{Do not create client-side decoration}. Some
users do not want decorations or wants minimal
decorations. Windows should look similar, server-side
@@ -426,10 +426,10 @@ of oversight from developers, client-side decoration
tends to work poorly with tiling window managers.
@item
-@cpindex{Memorisation of size and position}
-@cpindex{Position, memorisation}
-@cpindex{Size, memorisation}
-@pgindex{@command{mds-posmem}}
+@cpindex Memorisation of size and position
+@cpindex Position, memorisation
+@cpindex Size, memorisation
+@pgindex @command{mds-posmem}
@b{Do not remember size and position}. Some users
do not want their programs to remember their size
and position. There is also a risk that your
@@ -460,11 +460,11 @@ time they were closed.
@node Environment Variables
@section Environment Variables
-@cpindex{Environment variables}
-@vrindex{@env{DISPLAY}}
-@vrindex{@env{MDS_DISPLAY}}
-@cpindex{Display server identification}
-@cpindex{Identification, display server}
+@cpindex Environment variables
+@vrindex @env{DISPLAY}
+@vrindex @env{MDS_DISPLAY}
+@cpindex Display server identification
+@cpindex Identification, display server
A crucial task of any display server is letting child
processes know which display server they should
connect to. @command{X.org} does this by setting the
@@ -474,10 +474,10 @@ is empty if the display is one the local machine.
In this tradition @command{mds} does the same thing
with the environment variable @env{MDS_DISPLAY}.
-@cpindex{Environment variables}
-@vrindex{@env{MDS_PGROUP}}
-@cpindex{Display server process group}
-@cpindex{Process group, display server}
+@cpindex Environment variables
+@vrindex @env{MDS_PGROUP}
+@cpindex Display server process group
+@cpindex Process group, display server
@command{mds} also creates a new process group and
export the new process group ID to the environment
variable @command{MDS_PGROUP}. This process group
@@ -489,13 +489,13 @@ servers collectively.
@node Signals
@section Signals
-@cpindex{Signals}
-@cpindex{Re-executing servers}
-@cpindex{Updating, online}
-@cpindex{Online updating}
-@cpindex{Version update}
-@sgindex{@code{SIGUSR1}}
-@sgindex{@code{SIGUPDATE}}
+@cpindex Signals
+@cpindex Re-executing servers
+@cpindex Updating, online
+@cpindex Online updating
+@cpindex Version update
+@sgindex @code{SIGUSR1}
+@sgindex @code{SIGUPDATE}
@command{mds} servers can re-execute into an
updated version of their binary. This can be
used to update display server online after
@@ -507,24 +507,24 @@ If the operating system defines a signal named
@code{SIGUPDATE}, this signal is used
instead of @code{SIGUSR1}.
-@cpindex{Signals}
-@cpindex{Memory release, automatic}
-@cpindex{Memory release, forced}
-@cpindex{Automated memory release}
-@cpindex{Forcing memory release}
-@cpindex{Releasing memory}
-@sgindex{@code{SIGDANGER}}
-@sgindex{@code{SIGRTMIN + 1}}
+@cpindex Signals
+@cpindex Memory release, automatic
+@cpindex Memory release, forced
+@cpindex Automated memory release
+@cpindex Forcing memory release
+@cpindex Releasing memory
+@sgindex @code{SIGDANGER}
+@sgindex @code{SIGRTMIN + 1}
If you need servers to free up allocated
memory that they do not use, send the signal
@code{SIGDANGER}, or if not defined
@code{SIGRTMIN + 1}. Unimportant servers
may choose to die on @code{SIGDANGER}.
-@sgindex{@code{SIGINFO}}
-@sgindex{@code{SIGRTMIN + 2}}
-@cpindex{State dump}
-@cpindex{Statistics dump}
+@sgindex @code{SIGINFO}
+@sgindex @code{SIGRTMIN + 2}
+@cpindex State dump
+@cpindex Statistics dump
Server may also choose to support the signal
@code{SIGINFO}, or if not defined
@code{SIGRTMIN + 2}. It is not expected
@@ -534,8 +534,8 @@ is send by a user to the server, if she wants
the server to dump information about the
server's state or statistics to the TTY.
-@sgindex{@code{SIGRTMIN}}
-@cpindex{No-operation signal}
+@sgindex @code{SIGRTMIN}
+@cpindex No-operation signal
All servers configured to be interrupted
when the signal @code{SIGRTMIN} is received.
No further action is taked. This may be used
@@ -544,8 +544,8 @@ being interrupted. It can also be used by
the server to interrupt itself from another
thread.
-@pgindex{@command{valgrind}}
-@sgindex{@code{SIGRTMAX}}
+@pgindex @command{valgrind}
+@sgindex @code{SIGRTMAX}
@command{valgrind} uses @code{SIGRTMAX} for
its own internal stuff. Therefore servers must
not use @code{SIGRTMAX} as it is hence
@@ -556,9 +556,9 @@ unavailable when running under @command{valgrind}.
@node Filesystem
@section Filesystem
-@cpindex{Interprocess communication, filesystem}
-@cpindex{Filesystem}
-@cpindex{Kernel}
+@cpindex Interprocess communication, filesystem
+@cpindex Filesystem
+@cpindex Kernel
The @command{mds} kernel creates two directories
for the @command{mds} servers to use: one for
runtime data and one for temporary data.
@@ -578,10 +578,10 @@ For example if the display server index is zero,
temporary data may be stored in
@file{/tmp/.@{system-directory@}.mds/0.data}
-@cpindex{Re-executing servers}
-@cpindex{Updating, online}
-@cpindex{Online updating}
-@cpindex{Version update}
+@cpindex Re-executing servers
+@cpindex Updating, online
+@cpindex Online updating
+@cpindex Version update
As defined by @code{SHM_PATH_PATTERN} in
@file{<libmdsserver/config.h>}, when a server
re-executes itself it will marshal its state to
@@ -1059,6 +1059,9 @@ any other character, or multiple LF:s.
@node mds-respawn
@section @command{mds-respawn}
+@pgindex @command{mds-respawn}
+@cpindex Respawning servers, automatic
+@cpindex Crash resilience
@command{mds-respawn} is a utility intended to be used
in @file{$@{XDG_CONFIG_HOME@}/mdsinitrc}. It will spawn
a selected set of servers. If a server it spawns exits
@@ -1068,10 +1071,13 @@ line:
@table @option
@item --alarm=SECONDS
+@opindex @option{--alarm}
Schedule @command{mds-respawn} to die in @var{SECONDS}
seconds. At most 1 minute.
@item --interval=SECONDS
+@opindex @option{--interval}
+@sgindex @code{SIGUSR2}
Spawned servers that die twice with @var{SECONDS}
seconds should stop respawning until the signal
@code{SIGUSR2} is send to @command{mds-respawn}.
@@ -1082,12 +1088,17 @@ Commands for servers to spawn are specified within
curly braces. Each of the braces must be alone its
its own argument. For example:
+@opindex @option{--initial-spawn}
@example
mds-respawn --interval=5 \
@{ mds-foo --initial-spawn @} \
@{ mds-bar --initial-spawn @} &
@end example
+@cpindex Server supervision
+@cpindex Supervision of servers
+@opindex @option{--initial-spawn}
+@opindex @option{--respawn}
will spawn and supervise the servers @command{mds-foo}
and @command{mds-bar}. Both spawned with the
argument @option{--initial-spawn}. When a server is
@@ -1096,6 +1107,7 @@ in its argument list will be replaced by
@option{--respawn} to let the server know it is being
respawned.
+@sgindex @code{SIGTERM}
A server is considered to exit with a failure status
unless it exits with the return value 0 or is terminated
by the signal @code{SIGTERM}.
@@ -1105,6 +1117,11 @@ by the signal @code{SIGTERM}.
@node mds-reg
@section @command{mds-reg}
+@pgindex @command{mds-reg}
+@cpindex List protocols
+@cpindex Protocols, listing
+@opindex @option{--list}
+@opindex @option{--wait}
@command{mds-reg} is a utility that can be used to list
available protocols provided by running servers. It can
also wait for a set of protocols to become available. To
@@ -1121,38 +1138,48 @@ protocols.
@node mds-clip
@section @command{mds-clip}
+@pgindex @command{mds-clip}
+@cpindex Clipboard
@command{mds-clip} is a utility that can be used to
review the clipboards on the display and manipulate them.
@command{mds-clip} recognises the following options:
@table @option
@item --push
+@opindex @option{--push}
Push non-option arguments from the command line into
the clipboard.
@item --expire=SECONDS
+@opindex @option{--expire}
+@opindex @option{--push}
Can be used with @option{--push}. The clip will not
removed after @var{SECONDS} seconds.
@item --pop
+@opindex @option{--pop}
Pop items from the clipboard whose indices are listed
in the command line as non-option arguments. The first
index is 1.
@item --clear
+@opindex @option{--clear}
Pop all items in the clipboard.
@item --list
+@opindex @option{--list}
List items in the clipboard whose indices are listed
in the command line as non-option arguments. The first
index is 1. If no indicies are specified, all clips
will be listed.
@item --size
+@opindex @option{--size}
Print the size of the clipboard, the number of clips
in the clipboard.
@item --capacity
+@opindex @option{--capacity}
Print the capacity of the clipboard, the number of
clips the clipboard can hold. If both @option{--size}
and @option{--capacity} is used, the size will be
@@ -1160,15 +1187,21 @@ printed on the first line and the capacity will be
printed on the second line.
@item --resize=CAPACITY
+@opindex @option{--resize}
Change the capaciy of the clipboard to @var{CAPACITY}
clips.
@item --stdin
+@opindex @option{--stdin}
+@opindex @option{--push}
Can be used with @option{--push}. If used, the clip
that should be placed on the top of the clipboard
stack should be read from stdin.
@item --delimiter=DELIMITER
+@opindex @option{--delimiter}
+@opindex @option{--list}
+@opindex @option{--stdin}
Can be used with @option{--stdin} or @option{--list}.
If used with @option{--stdin}, an line containing
only @var{DELIMITER} will delimit two values that
@@ -1178,14 +1211,17 @@ will delimit two values in the output. The default
delimiter for @option{--list} is an empty line.
@item -1
+@opindex @option{-1}
Use the primary clipboard, that is, the text copy
clipboard. This is the default clipboard.
@item -2
+@opindex @option{-2}
Use the secondary clipboard, that is, the text
selection clipboard.
@item -3
+@opindex @option{-3}
Use the tertiary clipboard, that is, the non-text
copy clipboard.
@end table
@@ -1195,6 +1231,8 @@ copy clipboard.
@node mds-screenshot
@section @command{mds-screenshot}
+@pgindex @command{mds-screenshot}
+@cpindex Screenshooting
@command{mds-screenshot} is a simple utility, and
reference implementation thereof, that can take a
screeenshot of either the display, a monitor, or a
@@ -1205,46 +1243,58 @@ following options:
@table @option
@item --monitor
+@opindex @option{--monitor}
Take screenshot of the monitor. The rat will
be used to select monitor.
@item --monitor=WINDOW_ID
+@opindex @option{--monitor}
Take screenshot of the monitor whose root window's
window ID is @var{WINDOW_ID} or has another window
in it whose window ID is @var{WINDOW_ID}.
@item --embed
+@opindex @option{--embed}
Take a screenshot of an embedded window.
The rat will be used to select window.
@item --embed=WINDOW_ID
+@opindex @option{--monitor}
Take a screenshot of an embedded window whose
window ID is @var{WINDOW_ID}.
@item --window
+@opindex @option{--window}
Take a screenshot a window.
The rat will be used to select window.
@item --window=WINDOW_ID
+@opindex @option{--window}
Take a screenshot of a window whose
window ID is @var{WINDOW_ID}.
@item --decoration
+@opindex @option{--decoration}
Include the window's decoration, if used together
with @option{--window}. Ignored if used without
@option{--window}.
@item --cursor
+@opindex @option{--cursor}
Include the rat cursor in the screenshot.
@item --gamma
+@opindex @option{--gamma}
Include the effects of gamma ramps in the screenshot.
@item --low-gamma=LOW_PRIORITY
+@opindex @option{--low-gamma}
Include the effects of gamma ramps with a priority
above @var{LOW_PRIORITY} in the screenshot.
@item --high-gamma=HIGH_PRIORITY
+@opindex @option{--high-gamma}
+@opindex @option{--low-gamma}
Include the effects of gamma ramps with a priority
below @var{HIGH_PRIORITY} in the screenshot. If used
together with @option{--low-gamma=LOW_PRIORITY},
@@ -1255,10 +1305,16 @@ will be used.
Optionally, you can add a non-option argument that
specifies the pathname of the saved file.
+@opindex @option{--window}
+@opindex @option{--monitor}
+@opindex @option{--embed}
If neither @option{--monitor}, @option{--embed} or
@option{--window} is used, a screenshot will be
taked of the display. That is, all monitors.
+@opindex @option{--gamma}
+@opindex @option{--low-gamma}
+@opindex @option{--high-gamma}
In case of mirrored outputs, one of the potential
outputs will be selected arbitrarily if
@option{--gamma}, @option{--low-gamma} or
@@ -1271,6 +1327,9 @@ outputs.
@node mds-slay
@section @command{mds-slay}
+@pgindex @command{mds-slay}
+@cpindex Process killing
+@cpindex Killing processes
@command{mds-slay} a utility that can be used to
kill a process by it window or identify the window
ID of a window. @command{mds-slay} recognises the
@@ -1278,34 +1337,42 @@ following options:
@table @option
@item --embed
+@opindex @option{--embed}
Kill an embedded window.
The rat will be used to select window.
@item --embed=WINDOW_ID
+@opindex @option{--embed}
Kill an embedded window whose
window ID is @var{WINDOW_ID}.
@item --window
+@opindex @option{--window}
Kill a window.
The rat will be used to select window.
@item --window=WINDOW_ID
+@opindex @option{--window}
Kill a window whose
window ID is @var{WINDOW_ID}.
@item --signal=SIGNAL
+@opindex @option{--signal}
Send the signal @var{SIGNAL} to the
process owning the selected window.
@item --no-signal
+@opindex @option{--no-signal}
Do not send a signal; only identify the
window.
@item --keep-cursor
+@opindex @option{--keep-cursor}
Do not change the cursor to a kill cursor.
@item --print
-The the ID of the selected window.
+@opindex @option{--print}
+Print the ID of the selected window.
@end table
@@ -1313,6 +1380,10 @@ The the ID of the selected window.
@node mds-chvt
@section @command{mds-chvt}
+@pgindex @command{mds-chvt}
+@pgindex @command{chvt}
+@cpindex Virtual terminal, switching
+@cpindex Switching virtual terminal
@command{mds-chvt} is a utility similar to the command
@command{chvt} from the @command{kbd} project. However,
@command{mds-chvt} has setuid and therefore does not
@@ -1323,6 +1394,7 @@ recognises the following options:
@table @option
@item --switch=VT
+@opindex @option{--switch}
Switch to the virtual terminal with the index @var{VT}.
@end table
@@ -1330,6 +1402,12 @@ Switch to the virtual terminal with the index @var{VT}.
@node mds-kbdc
@section @command{mds-kbdc}
+
+@pgindex @command{mds-kbdc}
+@cpindex Keyboard layouts, compile
+@cpindex Compile keyboard layouts
+@cpindex Compose tables, compile
+@cpindex Compile compose tables
@command{mds-kbdc} is the program used to compile
keyboard layouts and compose tables.
@@ -1340,7 +1418,10 @@ TODO how to use mds-kbdc
@node External Utilities
@section External Utilities
-Servers let you use the option @command{--on-init-fork}
+@cpindex Background processes
+@opindex @option{--on-init-fork}
+@pgindex @file{mdsinitrc}
+Servers let you use the option @option{--on-init-fork}
to put the process in the background when it has been
initialised. This can used to spawn that depend on each
other in linear order. For example, if @command{mds-bar}
@@ -1353,6 +1434,11 @@ mds-foo --on-init-fork
mds-bar &
@end example
+@opindex @option{--on-init-fork}
+@opindex @option{--on-init-sh}
+@pgindex @command{mds-respawn}
+@pgindex @command{cmdipc}
+@pgindex @command{ipcmd}
This will start @command{mds-bar} when @command{mds-foo}
has been initialised. However if one of them crashes,
that server will not respawn; to fix this @command{mds-respawn}
@@ -1375,11 +1461,15 @@ cmdipc -Srk $S # Remove the semaphore.
mds-respawn @{ mds-bar @} & # Spawn `mds-bar`.
@end example
+@pgindex @command{mds-reg}
This is however seldom necessary as @command{mds-reg} can
often be used instead, with more abstraction as you would
only need to specify what servers need to wait for, not
what they provide.
+@pgindex @command{setpgrp}
+@cpindex Display server process group
+@cpindex Process group, display server
Another useful command (and package) is @command{setpgrp}.
@command{mds} puts itself an all its children in a new
process group. However you may want to put processes that
@@ -1392,6 +1482,10 @@ to starta process in a new process group.
@node Servers
@chapter Servers
+@pgindex @command{mds}
+@pgindex @command{mds-server}
+@cpindex Kernel
+@cpindex Master server
An @command{mds} display server instance is comprised of
multiple small servers that each implements a small part
of the display server's functionallity. This chapter will