


MKPATH(8)                                               MKPATH(8)


NAME
       mkpath - make a pathalias output file

SYNOPSIS
       /usr/lib/mail/mkpath [-v] [-V] [-x] [-e] [-n] [ -t trace ]
       [ path_config ]
       /usr/lib/mail/dcasehost [ -c ]

DESCRIPTION
       Mkpath creates pathalias(8) output given  a  configuration
       file that describes the various sources of input that will
       be used in generating this output, and how  these  sources
       of  input  are to be used.  The name of this configuration
       file is given as the path_config argument.  If path_config
       is -, then a specification will be taken from the standard
       input.  If path_config is omitted, then the default speci-
       fication  /usr/lib/mail/maps/mkpath.conf  is used.  Unless
       redirected in the configuration file, path data is written
       to the standard output.

       Dcasehost  converts  the hostname in a stream of pathalias
       data to lower case.  Normally, dcasehost assumes that  the
       hostname is in the first field in each line, where a field
       is delimited by whitespace.  If the -c  option  is  speci-
       fied,  then  the  hostname  is assumed to be in the second
       field.  This is for compatibility with the  -c  option  to
       pathalias(8).   See the pathalias man page for more infor-
       mation.

       The dcasehost command is intended to be used  only  within
       the mkpath command.

CONFIGURATION FILE FORMAT
       The  format  of  the  path  configuration file is a set of
       lines containing directives.  Blank lines are ignored  and
       the character ``#'' begins a comment which continues until
       the end of the line.  The various possible directives  are
       described below.

       In these directive descriptions, an argument of arg refers
       to one of the following types of arguments:

       'literal'        Literal data specified  inline.   (single
                        quotes)

       `shell-command`  Take  data  from  the  standard output of
                        this shell command.  (back quotes)

       filename ...     Take data from the named file  or  files.
                        Files  may be specified using shell glob-
                        bing notation, with * ?  and [].

       The `shell-command` form preserves newlines and whitespace
       and  is  thus  not  entirely equivalent to usage in sh(1).



Local                    31 January 1988                        1





MKPATH(8)                                               MKPATH(8)


       The following lines result in the same input to pathalias:

            map   `cat food`    # ackpft!
            map   food          # oop ack!

       For  the `shell-command` and 'literal' forms, the filename
       used for error messages is [stdin].

       map arg
              Specify map data to be given as input to pathalias.
              Each file is preceded by a line containing:

                   file { pathname }

              where  pathname  is  the full pathname to the file.
              This will cause error messages  from  pathalias  to
              refer  to  the correct file.  Each file is followed
              by the line containing:

                   private {}

              to force the end of scope for  any  private  direc-
              tives within the map files.

       safemap   arg
              This  is  similar  to the map directive, and can be
              used when you do not have sufficient  control  over
              what the files contain.  If a map file contains the
              pathalias  directives  delete  and  adjust,   those
              directives  are  removed  and  flagged  as  errors,
              before the file is passed to pathalias.  If  a  map
              file  contains  pathalias  file  directives,  those
              directives are simply removed.  No error message is
              produced in this case.

       delete arg
              Specify  hosts,  links  or networks which are to be
              deleted at this point.  That is, all previous  ref-
              erences to any of these items will be forgotten.

       adjust arg
              Specify  hosts  or networks that add on a surcharge
              to any route though them.  By  default,  this  sur-
              charge  is  4000.   Costs can also be added to each
              site as with pathalias.  For example, the following
              is a valid adjust file:

                   walldrug glotz              # default surcharge of 4000
                   kgbvax(1000), kremvax(DEAD) # surcharge of 1000 & DEAD
                   nsavax(FAST)                # reduces cost, FAST < 0

              Be  careful  when using negative adjust surcharges.
              The pathalias program will complain if a cost of  a
              link drops below zero.



Local                    31 January 1988                        2





MKPATH(8)                                               MKPATH(8)


       dead arg
              Specify  hosts,  links  or networks which are to be
              assigned a cost of DEAD.

       text arg
              Within an execution block,  described  in  a  later
              section,  the  given  specified text is sent as the
              standard input to a pathalias command.   Otherwise,
              it is written to the standard output for the mkpath
              command.

       file filename
              Set the file to be used by pathalias for error mes-
              sages,  starting  on  the  next  line  of pathalias
              input.  The next line will be  reported  as  if  it
              came from the first line of the file filename.  The
              file command does not change where  pathalias  will
              read  next,  only  what  pathalias  calls  the line
              should an error occur.

       cd [ dir ]
              By default, the current directory  used  by  mkpath
              begins  in the directory of the configuration file,
              or in the current directory if the configuration is
              read from the standard input.  The cd command with-
              out a dir argument changes to  the  directory  from
              which  mkpath  was invoked.  A dir arg of - changes
              the directory to the default directory based on the
              name  of  the  configuration  file.  Otherwise, dir
              becomes the current directory for  file  and  shell
              command references.

       sh cmd The given shell command is executed.

       pathalias flags
              Process  the  pathalias  input directives that have
              been collected since the last pathalias or pathsort
              directive and execute the pathalias(8) command with
              this input.  The specified flags are given as argu-
              ments  to  pathalias.  These flags can also contain
              i/o redirection, or pipes to other shell  commands.
              For  example, the following is an acceptable use of
              the pathalias directive:

                   pathalias -l hostname | mkdbm -o paths

       pathsort [ flags ]
              This is equivalent to the following directive:

                   pathalias -i -D | dcasehost  |  sort  -T  /tmp
                   flags ...

              An  example of a potentially useful pathsort direc-
              tive is:



Local                    31 January 1988                        3





MKPATH(8)                                               MKPATH(8)


                   pathsort | sed 's/!foo!/!foobar!/'
              A pathsort directive is assumed to follow  the  end
              of  a  configuration  file if an execution block is
              not terminated prior to the end of file.

EXECUTION BLOCKS
       Directives  are  executed  in  blocks.   A  map,  safemap,
       delete,  adjust,  dead  or  file directive starts a block.
       Successive directives continue it.  A pathalias  or  path-
       sort  directive ends a block.  The end of a file can end a
       block, generating an implicit pathsort directive.

       Encountering the end of a block normally  results  in  the
       execution  of  a  pathalias(8)  command.  The exception is
       when a end of block command is  read  when  no  block  was
       started.  In this case the block is ignored.

       When  the  start  of a block is seen, all directives up to
       the end of the  block  are  collected  and  fed  into  the
       resulting pathalias(8) command.  Directives such as cd, sh
       or text within a block only effect that block.  Therefore,
       a  cd directive within a block will only change the direc-
       tory for the remainder of that block, whereas a cd  direc-
       tive outside of a block has a global effect.

       Additionally a text or sh directive will feed its standard
       output into the  block's  pathalias  command  when  it  is
       inside  a block, while a text or sh directive outside of a
       block will send its output direct to the  standard  output
       of  the  mkpath command.  This later effect allows for the
       injection of literal  pathalias  output  into  the  output
       stream.

OPTIONS
       The following options are recognized by mkpath:

       -v     The  internal sh(1) commands are executed with a -v
              option, thus echoing the commands that are piped to
              the shell prior to their being processed.

       -V     Tell any pathalias commands to produce verbose mes-
              sages.

       -x     Pass the -x flag to invocations of the shell, caus-
              ing  commands  which  are  about  to  execute to be
              echoed.

       -e     Pass the -e flag to invocations of the shell, caus-
              ing  shells  to  exit  whenever a command returns a
              non-zero exit status.  In addition, the mkpath pro-
              gram will exit when it encounters a syntax error or
              unknown directive.

       -n     Disable the execution of any  shell  commands  that



Local                    31 January 1988                        4





MKPATH(8)                                               MKPATH(8)


              mkpath  generates.   This  is  useful  with  the -v
              option and disables the -x, -e and -V options.

       -t trace
              Cause the input to pathalias to be copied into  the
              file trace.


EXAMPLES
       Here is a simple example of a mkpath configuration file:

              # world.conf - configure our map setup to build world.map

              # get the usenet world maps
              cd      /usr/spool/uumaps
              safemap [ud].*

              # merge in the new maps
              cd      /usr/lib/smail/maps
              safemap newmap/*.map

              # delete our site and merge our private map data
              delete  `uuname -l`
              map     world.map private.map tweak.map

       This  configuration  file  can  be used for a UUCP gateway
       host:

              # Pathalias database for a UUCP gateway

              # map information is stored under this directory
              cd /usr/lib/smail

              # build paths to USENET hosts
              map       usenet/[du].*     # grab all published maps, start of block
              delete    `uuname -l`       # delete published references to our site
              dead      dead              # links and sites with cost of DEAD
              map       ourmap            # add our up-to-date map file
              pathsort  > paths.global    # end of block

              # build paths for our local domain
              map       local.map         # major domain info, start of block
              cd        ../uts            # cd only affects this block
              map       domain.map        # map for uts.amdahl.com domain
              adjust    'flaky'           # add 4000 to routes thru flaky
              adjust    'flako(HOURLY)'   # add HOURLY to routes thru flako
              pathsort  > paths.local     # end of block

              # build a sorted forces file, from the source forces file
              sh        mkline -t forces | dcasehost | sort -u +0 -1 > forces.sort

              # output paths and clean up
              sh        pathmerge forces.sort paths.local paths.global
              sh        rm -f forces.sort paths.local paths.global  # cleanup



Local                    31 January 1988                        5





MKPATH(8)                                               MKPATH(8)


SEE ALSO
       pathalias(8), mkline(8), mkdbm(8), mkhpath(8), mkuuwho(8),
       sort(1), sh(1), smail(5), smail(8) and pathmerge(8).

BUGS
       The  first  ``#''  character  on  a  line begins a comment
       regardless of whether or not it is within quotes.

       The -e option does not stop all  execution,  only  command
       execution  within  an  instance  of  the  shell created by
       mkpath.

       Continuation lines are not currently allowed in  the  con-
       figuration file.  Each command must be on a single line.

       For  errors reported by pathalias for input that came from
       the configuration file itself, the line number reported is
       likely  to be incorrect, because the pathalias file cannot
       be used to set a line number within the file.

       If both -V and -t are used, the -V option must precede  -t
       .

COPYRIGHT
       Copyright(C)1987, 1988 Ronald S. Karr and Landon Curt Noll
       Copyright(C)1992 Ronald S. Karr
       See a file COPYING, distributed with the source  code,  or
       type  smail  -bc  for distribution rights and restrictions
       associated with this software.




























Local                    31 January 1988                        6


