EFMD(8)                                                                EFMD(8)



NAME
       efmd - extraction filter for meta data files

SYNOPSIS
       efmd [-n] [-B macros] [-C configs] [-d flags] [-D|I|U m4-opts] [-E com-
       pares] [-F literal]  [-G  guard]  [-j  m4prep]  [-k  key]  [-M  prefix]
       [-o  attributes]  [-T header] [-X ex-configs] [-Y top] [-Z zero-config]
       [arguments]
       efmd -L [-B macros] [-C configs] [-d flags] [-D|I|U m4-opts]  [-E  com-
       pares]  [-G  guard]  [-j  m4prep]  [-k key] [-M prefix] [-o attributes]
       [-X ex-configs] [-Y top] [-Z zero-config]
       efmd -h
       efmd -V

DESCRIPTION
       Efmd extracts attributes from hxmd meta data files  into  a  stream  on
       stdout.   This  replaces  the -E option to the old distrib application.
       If you find yourself running the echo(1) command as the only shell com-
       mand in an hxmd control string, then you really wanted this program.

       Sometimes you just want a text report from the hxmd configuration data,
       not to fork hundreds of parallel processes.   In  that  case  you  want
       efmd,  which  only  forks  2  m4 processes to generate even the longest
       report.  (One to select the hosts, one to output the report.)

       The main advantage of efmd over hxmd is in a pipeline:  efmd  can  read
       stdin  and write to stdout, where hxmd may output results in a permuted
       order (due to the parallel process model it uses).

       Using hxmd to produce simple  reports  is  also  very  costly.   Common
       results  are  8x  to  50x  faster when efmd replaces hxmd for same text
       report generation.  For longer reports the  factor  gets  substantially
       larger, as many more process forks are avoided.

       The  arguments consist of regular files, FIFOs, literal strings, and/or
       cache directories (which must contain a "Cache.m4" recipe file  marked-
       up in m4).

       The m4 environment is almost identical to hxmd's, except the HXMD_PHASE
       lever only has two values: "selection" and "output".  The processing of
       each  arguments is undifferentiated by counting numbers, since the same
       m4 process filters them all.  This does allow an included macro file to
       tell  which  program  summoned  it  for inclusion, don't depend on that
       Easter Egg.

OPTIONS
       If the program is called as efmd then no options are forced.  When  the
       program is called with a name other than the usual that name is treated
       as the basename of a default configuration file.  Almost all  of  these
       options  are taken from hxmd, so you should read about them there.  I'm
       not going to repeat all the selection logic here.

       -B macros
              Boolean check, macros must be defined  to  select  host,  as  in
              hxmd.

       -C configs
              Files  of  hosts  and  attribute  macros, colon separated.  This
              option accumulates words separated by '':''.

       -d flags
              Debug flags we pass on to m4 ('?' for help).

       -D macro[=value] | -I file | -U macro
              Pass an option down to m4(1).

       -E compares
              Macro value must satisfy given relation to select hosts.

       -F literal
              The number of parameters which are  literal  text  (default  1).
              Processed  as hxmd does: negative values counted from the right,
              positive from the left.  Remaining arguments are taken as  files
              or cache directories.

       -G guard
              Expressions to select hosts by name.  See hxmd(8).

       -h
              Print only a brief help message.

       -j m4prep
              Each  m4prep  file contains macro definitions for m4 that may be
              consulted in any subsequent expansion.  It is not a good idea to
              include any directive that has output, as in hxmd.

       -k key
              Change the merge macro name from HOST to key.

       -L
              List the keys selected, but to not process any positional param-
              eters.  This is the cheap way to convert  a  configuration  file
              into just a list of hosts (for xapply or other similar filters).

       -M prefix
              Replace the "HXMD_" macro prefix with prefix.   This  option  is
              not included in the on-line help message, as most of the time it
              would be a bad idea to change it.

       -n
              Do not execute commands, trace only.  The output is  a  long  m4
              markup  script.   This  helps explain how things work, and might
              help you debug broken markup.

       -o attributes
              Output format of the merged  configuration  file.   This  option
              accumulates  words  separated  by tab (''\t'').  The name of the
              merged configuration file is always defined on the  command-line
              passed  to m4 as the first -D option.  That makes $1 "-D" and $2
              "HXMD_U_MERGED=path".

       -T header
              Output each of these at the top of the m4 markup.  This is  used
              for  headers,  to  setup  diversions,  or to install wrap logic.
              There is no "footer" hook since m4wrap works just fine.

       -V
              Show only version information.

       -X ex-configs
              Add attribute macro data to defined hosts, colon separated.

       -Y top
              M4 commands included at the top of the guard processing.

       -Z zero-config
              Configuration files to set default macro  values.   This  option
              accumulates words separated by '':''.

ENVIRONMENT
       HXMD_LIB
              As in hxmd, read configuration files from this path.  Also treat
              the first absolute path as the double-dash directory.

       M4_PATH
              If set we prefer this program as the  path  to  m4.   This  does
              allow  some clever hooks (TM).  Building a script that additionally
              processes the input markup from stdin before passing it  to  m4,
              or  passes  it  to m4 then takes some other action on the output
              before exiting might be clever.  For example, this is  the  best
              way to use HXMD_U_MERGED in a recursive call.

       TMPDIR
              As  always,  the  path  to  the  preferred  temporary file space
              (default /tmp).

EXAMPLES
       efmd -C example.cf -- "HOST ADMIN"
              Report the hostname and administrator for  each  host  in  exam-
              ple.cf.

       efmd -C example.cf -F1 HOST stock.m4
              Report  the  name  of  the  host  and  all the data requested by
              stock.m4 for each host from the first example.  Note that  "-F1"
              is the default.

       efmd -I -- -j class.m4 -C some.cf "HOST CLASSOF(HOST)"
              Use  a  local  macro  from  "class.m4"  to map each host to it's
              class.  This assumes that the file "class.m4" contains a defini-
              tion  of  the "CLASSOF" function, and no extra text (which would
              be noise in the output  stream).   The  -I  specification  helps
              locate  the  header  file, if it is in the default search direc-
              tory.

       efmd -V
              Shows the version of efmd, also the version of the  common  mod-
              ules taken from hxmd.

       efmd -C any.cf -D M -F0
              Just  check the file any.cf for structure.  No host are selected
              and no output should be generated.  Any output from the configu-
              ration file reader or from m4 represent errors in the the syntax
              of the file, or the markup in the attributes.

       efmd -C all.cf -E SHORTHOST=sulaco -j common.m4 -F0 header.m4 body.m4 next.m4
              Build a report for the host "sulaco"  from  the  markup  in  the
              three listed files, and the functions in the common file.

       M4_PATH='which less' efmd -C any.cf -F0
              Page the base markup to debug error reports from m4.

       efmd -L -C cvt.cf -E HOSTTYPE!unknown >host.cl
              Convert  the  configuration  in "cvt.cf" to a list of hosts, but
              skip the ones with HOSTTYPE set to "unknown".

       efmd -L -k SHORTHOST -C cvt.cf -E HOSTTYPE!unknown >host.cl
              This shows where -L differs from just putting HOST on the end of
              the command: since the key macro is SHORTHOST that is the column
              selected, and it only fork(2)'s a single m4 process.

       efmd -G"ifelse(yes,SERVICES(dns),HOST,yes,SERVICES(nis),HOST,yes,SERVICES(mux),HOST)" -Csite.cf -L
              List any host that provides at least 1 of these three  services:
              "dns", "nis", or "mux".  This is an "or" operation.

       cmd |efmd -C - ... -o ... -T "paste(HXMD_U_MERGED)dnl" dnl
              Use  efmd  as a configuration file filter: specify the selection
              criteria and the desired output format to complete the form.  By
              using  the  markup  "dnl"  for each host we emit no text for the
              hosts, while the top markup includes the text of the merged con-
              figuration file literally.

       efmd -C $FILE -T HXMD_OPT_C dnl
              Convert  the configuration filename given in "$FILE" into a full
              path to the file.  If the result contains a colon it may be more
              than 1 file, or a filename with an embedded colon.

       An example shim for M4_PATH that mocks -n:
              #!/bin/sh
              # Show exactly what efmd would process
              (
              echo $(which m4) $* '<<\!'
              cat -
              echo '\!'
              ) | ${PAGER:-less}
              exit 0

BUGS
       Efmd  masquerades  as  hxmd in terms of macro defines: it would be much
       harder to test markup for the two programs  when  they  used  different
       macro  names.   The  hidden option -M replaces the default macro prefix
       "HXMD_" with one of your choosing, should you need that.

       Access to cache directories by efmd is very expensive: almost as costly
       as  running  hxmd.  It is also likely that, for want of -K, -r, and -Q,
       the cache will not be cleaned after the access.

       The less(1) example above won't work with options passed through to  m4
       (under  -D, -I, -U, or -o) as less doesn't understand m4 options.  Code
       a simple shell script to filter the command line for any programs might
       want to run "under" efmd.

       The  -n option outputs some extra markup to mimic what m4 might do with
       -D, -I, -U, and -j options.  This  is  not  perfect  as  referenced  to
       HXMD_U_MERGED won't work, but it might work in other cases.

       The  environment  variable name M4_PATH is too close to the one m4 uses
       for its include path (M4PATH), which is is also a bug in hxmd.

       The command-line compatibility with most of the options to hxmd is  not
       a bug, even if you think it is.

AUTHOR
       KS Braunsdorf, NonPlayer Character Guild
       hxmd span-me-not at-ksb dotty NPC Guild dot org.

SEE ALSO
       sh(1), m4(1), hxmd(8l), hxmd(5l), mmsrc(8l), distrib(8l), xapply(1l)



                                     LOCAL                             EFMD(8)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | ENVIRONMENT | EXAMPLES | BUGS | AUTHOR | SEE ALSO