getmap(8)
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 /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 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. 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 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 /. 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, 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 /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 artcile
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 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
for distribution rights and restrictions associated with this software.