


GETMAP(8)                                               GETMAP(8)


NAME
       getmap - unshar USENET map articles into a map directory

SYNOPSIS
       /usr/lib/mail/getmap [ -m mapdir ] [ -w workdir ]
                 [ -b batch ] [ -u address ] [ -n newsgroups ]
                 [ -s newsspooldir ]
       /usr/lib/mail/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
              /usr/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
              /usr/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  arti-
              cles.   Multiple newsgroups can be specified, sepa-
              rated  by  single  colons.   The  default  list  is
              ``comp.mail.maps.''



Local                    31 January 1988                        1





GETMAP(8)                                               GETMAP(8)


       -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.  The
              default news spool directory is /usr/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.

       -n newsgroups
              Specifiy the list of allowed newsgroups  for  arti-
              cles.   Multiple newsgroups can be specified, sepa-
              rated  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 /.  However, if
              invoked   from    getmap,    this    defaults    to
              /usr/spool/news.

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,



Local                    31 January 1988                        2





GETMAP(8)                                               GETMAP(8)


       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 direc-
       tory.  Old map files are overwritten.

       For each map file, unsharmap writes the following informa-
       tion 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 encoun-
       tered, 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, indepen-
       dently of case.

       The  body  for each article file is expected to begin with
       zero or more lines beginning with the character `:',  fol-
       lowed 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,  fol-
       lowed by the three lines:

              SHAR_EOF



Local                    31 January 1988                        3





GETMAP(8)                                               GETMAP(8)


              :    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 /usr/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
       /usr/spool/news
                      The default top-level  directory  used  for
                      obtaining news articles.

       /usr/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.

       /usr/spool/uumaps/work/batch
                      The  default work file used containing art-
                      cile filenames.

       /usr/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.

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

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

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

       /bin/smail     The  program used in mailing the getmap.err



Local                    31 January 1988                        4





GETMAP(8)                                               GETMAP(8)


                      error log.

SEE ALSO
       news(5), inews(1), smail(5), article(5), smail(8),  smail-
       cron(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 for distribution  rights  and  restrictions
       associated with this software.



































Local                    31 January 1988                        5


