--- name: "getmap" section: "8" platform: "linux" package: "smail" version: "3.2.0.115-7.1" release: "Debian 4.0 (Etch)" platforms: ["linux"] url: "https://new.carta.tech/getmap" --- # getmap(8) unshar USENET map articles into a map directory ## 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)](/pathalias/8.md). The program [*uuwho*(1)](/uuwho/1.md) 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)](/news/5.md)) 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)](/news/5.md), [*inews*(1)](/inews/1.md), [*smail*(5)](/smail/5.md), *article*(5), [*smail*(8)](/smail/8.md), *smailcron*(8), [*uuwho*(1)](/uuwho/1.md), [*mkpath*(8)](/mkpath/8.md) and [*pathalias*(8)](/pathalias/8.md). ## 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.