doc/fvwm/modules.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   3   "../docbook-xml/docbookx.dtd"
   4 [
   5 <!ENTITY % myents SYSTEM "../fvwm.ent" >
   6 %myents;
   7 ]>
   8
   9 <section id='modules'>
  10 <title>Modules</title>
  11 <para>A module is a separate program which runs as a separate Unix
  12 process but transmits commands to fvwm to execute.  Users can
  13 write their own modules to do any weird or bizarre manipulations
  14 without bloating or affecting the integrity of fvwm itself.</para>
  15
  16 <para>Modules must be spawned by fvwm so that it can set up two pipes
  17 for fvwm and the module to communicate with.  The pipes are
  18 already open for the module when it starts and the file
  19 descriptors for the pipes are provided as command line arguments.</para>
  20
  21 <para>Modules can be spawned by fvwm at any time during the X session by
  22 use of the
  23 <fvwmref cmd="Module"/>
  24 command.  Modules can exist for the duration of the X
  25 session, or can perform a single task and exit.  If the module is
  26 still active when fvwm is told to quit, then fvwm closes the
  27 communication pipes and waits to receive a SIGCHLD from the
  28 module, indicating that it has detected the pipe closure and has
  29 exited.  If modules fail to detect the pipe closure fvwm exits
  30 after approximately 30 seconds anyway.  The number of
  31 simultaneously executing modules is limited by the operating
  32 system's maximum number of simultaneously open files, usually
  33 between 60 and 256.</para>
  34
  35 <para>Modules simply transmit commands to the fvwm command
  36 engine.  Commands are formatted just as in the case of a
  37 mouse binding in the
  38 <filename>config</filename>
  39 setup file.  Certain auxiliary information is also transmitted, as
  40 in the sample module
  41 <fvwmref mod="FvwmButtons"/>.
  42 </para>
  43 <para>Please refer to the
  44 <fvwmref sect="moduleCommands" opt="module_commands" name="Module Commands"/>
  45 section for details.</para>
  46
  47 </section>