diff options
| -rw-r--r-- | doc/info/mds.texinfo | 189 |
1 files changed, 189 insertions, 0 deletions
diff --git a/doc/info/mds.texinfo b/doc/info/mds.texinfo index 49e581c..96310d3 100644 --- a/doc/info/mds.texinfo +++ b/doc/info/mds.texinfo @@ -5666,6 +5666,7 @@ in the display server message passing system. @node mds-base.o @chapter @file{mds-base.o} +@cpindex @file{mds-base} @file{mds-base.c} and @file{mds-base.h} as an object filepair whose purpose is similar to libmdsserver. @file{mds-base} is compiled into all @command{mds} @@ -5682,6 +5683,8 @@ be implement depending on specified conditions: @table @asis @item @code{trap_signals} [(@code{void}) @arrow{} @code{int}] +@fnindex @code{trap_signals} +@cpindex Signals Set up signal traps for all especially handled signals. Returns zero on and only on success. @end table @@ -5691,6 +5694,9 @@ replace if they do not suit your needs: @table @asis @item @code{parse_cmdline} [(@code{void}) @arrow{} @code{int}] +@fnindex @code{parse_cmdline} +@cpindex Parse command line +@cpindex Command line, parse Parses command line arguments. Returns zero on and only on success. @@ -5698,50 +5704,75 @@ This function will parse the following options: @table @option @item --initial-spawn +@opindex @option{--initial-spawn} It is the first time the server is spawn by its spawner process. @item --respawn +@opindex @option{--respawn} The server was respawned. @item --re-exec +@opindex @option{--re-exec} The server is re-executing. @item --alarm=SECONDS +@opindex @option{--alarm} Kill the process after @var{SECONDS} seconds. At most one minute. @item --on-init-fork +@opindex @option{--on-init-fork} Fork the process to detach it from its parent when the server has been initialised. @item --on-init-sh=COMMAND +@opindex @option{--on-init-sh} When the server has been initialised, run the command @var{COMMAND}. @item --immortal +@opindex @option{--immortal} The server should do its best not to die. For example do not die if @code{SIGDANGER} is received even if that is the server's default action. @end table @item @code{connect_to_display} [(@code{void}) @arrow{} @code{int}] +@fnindex @code{connect_to_display} +@cpindex Connecting to the display Connects to the display. Returns zero on and only on success. @item @code{server_initialised} [(@code{void}) @arrow{} @code{int}] +@fnindex @code{server_initialised} +@cpindex Initialisation This function should be called when the server has been properly initialised but before initialisation of anything that is removed at forking is initialised. Returns zero on and only on success. @item @code{signal_all} [(@code{int signo}) @arrow{} @code{void}] +@fnindex @code{signal_all} +@cpindex Signals, multi-threading +@cpindex Multi-threading, signals +@cpindex Treading, signals This function should be implemented by the actual server implementation if the server is multi-threaded. It sends the singal @code{signo} to all threads except the current thread. @item @code{received_danger} [(@code{int signo}) @arrow{} @code{void}] +@fnindex @code{received_danger} +@sgindex @code{SIGDANGER} +@vrindex @code{server_characteristics.danger_is_deadly} +@vrindex @code{danger_is_deadly} +@cpindex Memory release, automatic +@cpindex Memory release, forced +@cpindex Automated memory release +@cpindex Forcing memory release +@cpindex Releasing memory +@vrindex @code{danger} This function is called when a signal that signals the system is running out of memory has been received. The exact received signal is specified by the parameter @code{signo}. @@ -5752,6 +5783,15 @@ If @code{server_characteristics.danger_is_deadly} is set, this function will never be called. @item @code{received_reexec} [(@code{int signo}) @arrow{} @code{void}] +@fnindex @code{received_reexec} +@vrindex @code{reexecing} +@vrindex @code{terminating} +@cpindex Re-executing servers +@cpindex Updating, online +@cpindex Online updating +@cpindex Version update +@sgindex @code{SIGUSR1} +@sgindex @code{SIGUPDATE} This function is called when a signal that signals the server to re-execute has been received. The exact received signal is specified by the parameter @code{signo}. @@ -5759,6 +5799,11 @@ When this function is invoked, it should set the variables @code{reexecing} and @code{terminating} to a non-zero value. @item @code{received_terminate} [(@code{int signo}) @arrow{} @code{void}] +@fnindex @code{received_terminate} +@vrindex @code{terminating} +@cpindex Terminating +@sgindex @code{SIGTERM} +@sgindex @code{SIGINT} This function is called when a signal that signals the server to terminate has been received. The exact received signal is specified by the parameter @code{signo}. When @@ -5766,12 +5811,20 @@ this function is invoked, it should set the variable @code{terminating} to a non-zero value. @item @code{received_info} [(@code{int signo}) @arrow{} @code{void}] +@fnindex @code{received_info} +@sgindex @code{SIGINFO} +@cpindex State dump +@cpindex Statistics dump This function is called when a signal that signals the server to dump state information and statistics has been received. The exact received signal is specified by the parameter @code{signo}. @item @code{fork_cleanup} [(@code{int status}) @arrow{} @code{void}] +@fnindex @code{fork_cleanup} +@vrindex @code{server_characteristics.fork_for_safety} +@vrindex @code{fork_for_safety} +@cpindex Initialisation This function should be implemented by the actual server implementation if the server has set @code{server_characteristics.fork_for_safety} to be a @@ -5787,20 +5840,38 @@ to define and implement a set of functions: @table @asis @item @code{preinitialise_server} [(@code{void}) @arrow{} @code{int}] +@fnindex @code{preinitialise_server} +@fnindex @code{initialise_server} +@fnindex @code{unmarshal_server} +@cpindex Initialisation This function will be invoked before @code{initialise_server} (if not re-executing) or before @code{unmarshal_server} (if not re-executing). Returns zero on and only on success. @item @code{initialise_server} [(@code{void}) @arrow{} @code{int}] +@fnindex @code{initialise_server} +@cpindex Initialisation This function should initialise the server. It not invoked after a re-execution. Returns zero on and only on success. @item @code{postinitialise_server} [(@code{void}) @arrow{} @code{int}] +@fnindex @code{postinitialise_server} +@fnindex @code{initialise_server} +@fnindex @code{unmarshal_server} +@cpindex Initialisation This function will be invoked after @code{initialise_server} (if not re-executing) or after @code{unmarshal_server} (if re-executing). Returns zero on and only on success. @item @code{marshal_server_size} [(@code{void}) @arrow{} @code{size_t}, pure] +@fnindex @code{marshal_server_size} +@fnindex @code{marshal_server} +@cpindex Re-executing servers +@cpindex Updating, online +@cpindex Online updating +@cpindex Version update +@sgindex @code{SIGUSR1} +@sgindex @code{SIGUPDATE} Calculate and returns the number of bytes that will be stored by @code{marshal_server}. On failure the server should call @code{abort} or exit with failure status by other means. @@ -5809,14 +5880,29 @@ However it should not be possible for this function to fail. define with and conforming to @code{__attribute__((pure))}.}. @item @code{marshal_server} [(@code{char* state_buf}) @arrow{} @code{int}] +@fnindex @code{marshal_server} +@cpindex Re-executing servers +@cpindex Updating, online +@cpindex Online updating +@cpindex Version update +@sgindex @code{SIGUSR1} +@sgindex @code{SIGUPDATE} Marshal server implementation specific data into the buffer @code{state_buf}. Returns zero on and only on success. @item @code{unmarshal_server} [(@code{char* state_buf}) @arrow{} @code{int}] +@fnindex @code{unmarshal_server} +@cpindex Re-executing servers +@cpindex Updating, online +@cpindex Online updating +@cpindex Version update +@sgindex @code{SIGUSR1} +@sgindex @code{SIGUPDATE} Unmarshal server implementation specific data from the buffer @code{state_buf} and update the servers state accordingly. Returns zero on and only on success. +@fnindex @code{reexec_failure_recover} On critical failure the program should call @code{abort} or exit with failure status by other means. That is, do not let @code{reexec_failure_recover} run successfully, if it @@ -5824,11 +5910,20 @@ unrecoverable error has occurred or one severe enough that it is better to simply respawn. @item @code{reexec_failure_recover} [(@code{void}) @arrow{} @code{int}] +@fnindex @code{reexec_failure_recover} +@cpindex Re-executing servers +@cpindex Updating, online +@cpindex Online updating +@cpindex Version update +@sgindex @code{SIGUSR1} +@sgindex @code{SIGUPDATE} Attempt to recover from a re-execution failure that has been detected after the server successfully updated it execution image. Returns zero on and only on success. @item @code{master_loop} [(@code{void}) @arrow{} @code{int}] +@fnindex @code{master_loop} +@cpindex Initialisation Perform the server's mission. Returns zero on and only on success. @end table @@ -5836,53 +5931,96 @@ Perform the server's mission. Returns zero on and only on success. @table @asis @item @code{argc} [@code{int}] +@vrindex @code{argc} +@cpindex Command line Number of elements in @code{argv}. @item @code{argv} [@code{char**}] +@vrindex @code{argv} +@cpindex Command line Command line arguments. @item @code{is_respawn} [@code{int}] +@vrindex @code{is_respawn} +@cpindex Initialisation +@vrindex @code{is_reexec} Whether the server has been respawn rather than this being the initial spawn. This will be at least as true as @code{is_reexec}. @item @code{is_reexec} [@code{int}] +@vrindex @code{is_reexec} +@cpindex Initialisation +@cpindex Re-executing servers +@cpindex Updating, online +@cpindex Online updating +@cpindex Version update +@sgindex @code{SIGUSR1} +@sgindex @code{SIGUPDATE} Whether the server is continuing from a self-reexecution. @item @code{is_immortal} [@code{int}] +@vrindex @code{is_immortal} +@opindex @option{--immortal} Whether the server should do its best to resist event triggered death. @item @code{on_init_fork} [@code{int}] +@vrindex @code{on_init_fork} +@cpindex Initialisation Whether to fork the process when the server has been properly initialised. @item @code{on_init_sh} [@code{char*}] +@vrindex @code{on_init_sh} +@cpindex Initialisation Command the run (@code{NULL} for none) when the server has been properly initialised. @item @code{master_thread} [@code{pthread_t}] +@vrindex @code{master_thread} +@cpindex Threading +@cpindex Multi-threading The thread that runs the master loop. @item @code{terminating} [@code{volatile sig_atomic_t}] +@vrindex @code{terminating} +@cpindex Terminating Whether the server has been signaled to terminate. @item @code{reexecing} [@code{volatile sig_atomic_t}] +@vrindex @code{reexecing} +@cpindex Initialisation +@cpindex Re-executing servers +@cpindex Updating, online +@cpindex Online updating +@cpindex Version update Whether the server has been signaled to re-execute. @item @code{danger} [@code{volatile sig_atomic_t}] +@vrindex @code{danger} +@sgindex @code{SIGDANGER} +@cpindex Memory release, automatic +@cpindex Memory release, forced +@cpindex Automated memory release +@cpindex Forcing memory release +@cpindex Releasing memory Whether the server has been signaled to free unneeded memory. @item @code{socket_fd} [@code{int}] +@vrindex @code{socket_fd} +@cpindex Connecting to the display The file descriptor of the socket that is connected to the server. @end table +@cpindex Server characteristics @file{mds-base} expects the server implementation to define a variable that specifies how @file{mds-base} should behave: @table @asis @item @code{server_characteristics} [@code{server_characteristics_t}] +@vrindex @code{server_characteristics} This variable should declared by the actual server implementation. It must be configured before @code{main} is invoked. That is, it should be configured by a @@ -5891,6 +6029,8 @@ it is configured by a constructor; that is normally how you want to configured it. @end table +@tpindex @code{server_characteristics_t} +@tpindex @code{struct server_characteristics} @code{server_characteristics_t} @{also known as @code{struct server_characteristics}@} is a packed @footnote{That is, define with @code{__attribute__((packed))}.} @@ -5898,23 +6038,38 @@ with the following fields: @table @asis @item @code{require_privileges} [@code{unsigned : 1}] +@vrindex @code{require_privileges} +@cpindex Previleges +@cpindex Security, previleges Setting this to zero will cause the server to drop privileges as a security precaution. @item @code{require_display} [@code{unsigned : 1}] +@vrindex @code{require_display} +@cpindex Connecting to the display Setting this to non-zero will cause the server to connect to the display. @item @code{require_respawn_info} [@code{unsigned : 1}] +@vrindex @code{require_respawn_info} +@opindex @option{--initial-spawn} +@opindex @option{--respawn} +@cpindex Initialisation Setting this to non-zero will cause the server to refuse to start unless either @option{--initial-spawn} or @option{--respawn} is used. @item @code{sanity_check_argc} [@code{unsigned : 1}] +@vrindex @code{sanity_check_argc} +@cpindex Command line, security +@cpindex Security, command line Setting this to non-zero will cause the server to refuse to start if there are too many command line arguments. @item @code{fork_for_safety} [@code{unsigned : 1}] +@vrindex @code{fork_for_safety} +@cpindex Initialisation +@fnindex @code{fork_cleanup} Setting this to non-zero will cause the server to place itself in a fork of itself when initialised. This can be used to let the server clean up fatal stuff after itself @@ -5923,6 +6078,15 @@ exits, the parent will call @code{fork_cleanup} and then die in the same manner as the child. @item @code{danger_is_deadly} [@code{unsigned : 1}] +@vrindex @code{danger_is_deadly} +@sgindex @code{SIGDANGER} +@vrindex @code{fork_for_safety} +@fnindex @code{server_initialised} +@cpindex Memory release, automatic +@cpindex Memory release, forced +@cpindex Automated memory release +@cpindex Forcing memory release +@cpindex Releasing memory Setting this to non-zero without setting a signal action for @code{SIGDANGER} will cause the server to die if @code{SIGDANGER} is received. It is safe to set both @@ -5933,6 +6097,7 @@ process will be set to @code{SIG_IGN} independently of the value of @code{danger_is_deadly} if @code{fork_for_safety} is set to non-zero. +@opindex @option{--immortal} This setting will be treated as set to zero if @option{--immortal} is used. @end table @@ -5942,6 +6107,7 @@ This setting will be treated as set to zero if @node Keyboard Codes @chapter Keyboard Codes +@cpindex Scancodes Keyboard servers receive scancodes from keyboard drivers. A scancode can either be comprised of one byte or three bytes. In each byte, the most @@ -5955,6 +6121,7 @@ A scancode is comprised of three bytes if the lower 7-bits of the first byte is are all cleared, and the highest bit in the two following bytes are set. +@cpindex Keycodes Ignoring the most significant bit in all bytes, the keycode is the value of the byte if the scancode is a single byte scancode. If the scancode is comprised @@ -7665,6 +7832,10 @@ can be composed with a trailing @kbd{<space>} instead of leading @node Sticky Keys @section Sticky Keys +@pgindex @command{mds-keystick} +@cpindex Sticky keys +@cpindex Keyboard, accessibility +@cpindex Accessibility, keyboard Sticky keys is an accessibility feature that lets the user process modifier keys instead of holding them down. Sticky keys is implemented by the @command{mds-keystick} @@ -7692,6 +7863,8 @@ so means that you do not have to configure @command{mds-keystick} to know the original @kbd{caps lock} is a modifier but the original @kbd{control} is not. +@cpindex Mode lock key +@cpindex Keys, mode lock For greater accessibility you can, in @command{mds-keytrans}, replace a key with the @kbd{mode lock}-key. If this is done, pressing a sequence of modifiers and then the @@ -7708,6 +7881,10 @@ stickly keys are artificially held down and thus included. @node Bounce Keys @section Bounce Keys +@pgindex @command{mds-keybounce} +@cpindex Bounce keys +@cpindex Keyboard, accessibility +@cpindex Accessibility, keyboard Bounce keys is an accessibility feature that filters out rapidly repeated key strokes. Bounce keys is implemented by the @command{mds-keybounce} server. @@ -7717,6 +7894,10 @@ by the @command{mds-keybounce} server. @node Slow Keys @section Slow Keys +@pgindex @command{mds-slowkey} +@cpindex Slow keys +@cpindex Keyboard, accessibility +@cpindex Accessibility, keyboard Slow keys is an accessibility feature that filters out brief key strokes. Slow keys is implemented by the @command{mds-slowkey} server. @@ -7726,6 +7907,10 @@ brief key strokes. Slow keys is implemented by the @node Loud Keys @section Loud Keys +@pgindex @command{mds-keycue} +@cpindex Loud keys +@cpindex Keyboard, accessibility +@cpindex Accessibility, keyboard Loud keys is an accessibility feature that can emulate key clicking sounds when a key is pressed or generate tones when certain keys are pressed. For example if @@ -7739,6 +7924,10 @@ implemented by the @command{mds-keycue} server. @node Mouse Keys @section Mouse Keys +@pgindex @command{mds-kbd2rat} +@cpindex Keyboard to rat bindings +@cpindex Rat keys +@cpindex Mouse keys Rat keys (also known as mouse keys) is an accessibility and usability feature that lets the user use the keyboard as a pointing device. This feature is implemented by the |