Provided by: smail_3.2.0.115-7_i386 bug

NAME

       getmap - unshar USENET map articles into a map directory

SYNOPSIS

       /usr/lib/smail/getmap [ -m mapdir ] [ -w workdir ]
                 [ -b batch ] [ -u address ] [ -n newsgroups ]
                 [ -s newsspooldir ]
       /usr/lib/smail/unsharmap [ -d dir ] [ -n newsgroups ]
                 [ -s newsspooldir ]

DESCRIPTION

       The getmap command reads the file batch to obtain a list of article
       files formatted in the style of USENET comp.mail.maps.  It then uses
       unsharmap to extract maps from these articles into the directory
       mapdir.  These maps are intended to be used as input data to
       pathalias(8).  The program uuwho(1) prints individual map entries from
       the extracted map files.

OPTIONS

       The following options are recognized by getmap:

       -m mapdir
              Extracted map files will be placed in the directory mapdir,
              rather than the default directory /var/spool/uumaps.

       -w workdir
              The directory workdir will be used for working storage for
              getmap .  The log and error log files getmap.log and getmap.err
              will also be placed in this directory.

       -b batch
              Use batch, rather than /var/spool/uumaps/work/batch, as the name
              of the file containing the list of new mail message files.  A
              batch file of - implies that the list of articles is to be read
              from standard input.  If batch is not - then batch.work is used
              as both the lock file and the work file.

       -u address
              If getmap encounters an error, then the contents of the error
              log file will be mailed to address rather than the default
              address of Postmaster.  If address is - then the error log is
              written to standard error rather than mailed to some user.

       -n newsgroups
              Specifiy the list of allowed newsgroups for articles.  Multiple
              newsgroups can be specified, separated by single colons.  The
              default list is ‘‘comp.mail.maps.’’

       -s newsspooldir
              Specify the top-level directory of the news article hierarchy.
              Batch files created by C News contain pathnames that are
              relative to this directory.  If this option is not specified,
              the batch file must contain pathnames that begin with a slash
              (‘/’).  However, if invoked from getmap, this defaults to
              /var/spool/news.

       Even though the default values for mapdir , workdir and batch are found
       in the same directory tree, the options -m, -w, and -b set locations
       independent of each other.  E.g., -m does not change workdir .

       The following options are recognized by unsharmap:

       -d dir Map files are extracted into dir rather than the current
              directory.

GETMAP OPERATION

       The batch file contains a list of article filenames, one per line.
       Article files are files formatted in the style of articles received by
       the USENET news service in the newsgroup comp.mail.maps.  The getmap
       program uses unsharmap to extact a map file from each artcile named in
       the batch file.  All extacted map articles are placed in the directory
       mapdir.  A log of each article file is obtained from the standard
       output of unsharmap and appended to the file getmap.log located in the
       workdir directory.

       At invocation, getmap attemps to move batch to a file with a .work
       suffix.  (i.e., batch is moved to batch.work .)  If batch.work already
       exists, getmap will abort.  In this way, the batch.work serves as a
       lock file.  If batch is - then article file names are obtained form
       standard input.  In this case, the batch.work file is not formed.

       The file getmap.log in the directory workdir contains a history of
       getmap processing and errors.  At the start of a given getmap run, the
       error log file getmap.err in the directory workdir is cleared.  During
       getmap execution, each line written to the log file is also written to
       the error log file.  If any error conditions are encountered, the error
       log is mailed to address.  If address is - then the error log is
       written to standard error.  If no errors are encountered, the error log
       is removed, otherwise it is left behind until a future getmap run
       clears it.

UNSHARMAP OPERATION

       The unsharmap program is used by getmap to extract maps out of article
       files.

       Article file names are read from standard input, one file per line.
       The map file name is obtained form the article file and the map
       contents are written into the dir directory.  Old map files are
       overwritten.

       For each map file, unsharmap writes the following information to
       standard output:

              name of the article file
              name of the extracted map file
              Subject line
              Message-ID line
              article Date
              Approved line

       Each article file contains a news header, a blank line, and an article
       body.  The header, which starts on the first line and continues until a
       blank line is encountered, which separates the header from the body.
       The header is expected to contain at least the following header fields:
              Newsgroups: comp.mail.maps
              Subject: UUCP ...
              Message-ID: ...
              Date: ...
              Approved: ...
       For any line above, containing ‘...’, the ‘...’ string can match any
       sequence of characters within a field, where other characters in the
       field must match exactly, independently of case.

       The body for each article file is expected to begin with zero or more
       lines beginning with the character ‘:’, followed by the two lines:

              echo shar: extracting map-name
              cat << ’SHAR_EOF’ > map-name

       where map-name is the map to be extracted.  What follows are the file
       contents to be placed in the map file, followed by the three lines:

              SHAR_EOF
              :    End of shell archive
              exit 0

INTERFACING GETMAP WITH NETNEWS

       To interface getmap with the netnews software, version 2.10 or 2.11,
       add a line to your sys file (see news(5)) containing:

              maps:comp.mailmaps,world:F:batch

       where batch is the full pathname to getmap’s batch file.  Normally
       batch is /var/spool/uumaps/work/batch.

       The getmap program should be run on a periodic basis under a user and
       group ID that can write to the map directory.  See smailcron(8) for
       details.

FILES

       /var/spool/news
                      The default top-level directory used for obtaining news
                      articles.

       /var/spool/uumaps
                      The default directory for maps extraction.  Map files
                      broadcast in comp.mail.maps begin with either ‘‘u.’’ or
                      ‘‘d.’’ and have a name indicating which region of the
                      world they represent.

       /var/spool/uumaps/work/batch
                      The default work file used containing artcile filenames.

       /var/spool/uumaps/work/batch.work
                      The default work file copy created while processing the
                      input pathnames.  This file also serves as a lock file
                      for similar getmap executions.

       /var/spool/uumaps/work/getmap.log
                      The default history log of getmap activity and errors.

       /var/spool/uumaps/work/getmap.err
                      The default error log of the previous getmap execution.
                      This is mailed to Postmaster if an error occured,
                      otherwise it is removed.

       /usr/lib/smail/unsharmap
                      The program that does the real work of extracting map
                      files from netnews articles.

       /usr/sbin/smail
                      The program used in mailing the getmap.err error log.

SEE ALSO

       news(5), inews(1), smail(5), article(5), smail(8), smailcron(8),
       uuwho(1), mkpath(8) and pathalias(8).

BUGS

       The format of USENET articles is subject to change at the whim of a few
       USENET map people.

       some articles may not be processed.  Most netnews software does an
       open, write and close for each filename written to the batch file.  In
       rare cases, the batch file may be left opened when getmap moved it to
       batch.work.  In this case, the last article may be ignored.

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, to view distribution rights and restrictions associated with this
       software.