Provided by: cnews_cr.g7-39_i386 bug

NAME

       expire, doexpire, expireiflow - expire old news
       upact - update news active file

SYNOPSIS

       /usr/lib/news/expire/expire  [ -a archdir ] [ -p ] [ -s ] [ -F c ] [ -c
       ] [ -n nnnnn ] [ -t ] [ -l ] [ -v ] [ -d ] [ -r ] [ -g ] [ -h  ]  [  -H
       historydir ] [ controlfile ]
       /usr/lib/news/expire/doexpire [ expireoptions ] [ -f ] [ -e ]
       /usr/lib/news/expire/expireiflow minimum expireoptions
       /usr/lib/news/expire/upact [ -b ] [ -p ] [ -s ] [ -# ]

DESCRIPTION

       Expire  expires old news, removing it from the current-news directories
       and (if asked to) archiving it elsewhere.  It  updates  news’s  history
       file  to  match.   Expire  should normally be run nightly, typically by
       using doexpire (see below).

       Expire’s operations are controlled by a  control  file  (which  can  be
       named or supplied on standard input), which is not optional—there is no
       default behavior.  Each line of the  control  file  (except  for  empty
       lines  and lines starting with ‘#’, which are ignored) should have four
       white-space-separated fields, as follows.

       The first field is a newsgroup pattern list  (containing  no  spaces!);
       partial specifications are acceptable (e.g. ‘comp’ specifies all groups
       with that prefix).  See newssys(5) for full details.

       The second field is one letter, ‘m’, ‘u’, or ‘x’, specifying  that  the
       line  applies  only to moderated groups, only to unmoderated groups, or
       to both, respectively.

       The third field specifies the expiry period in days.  The most  general
       form is three numbers separated by dashes.  The units are days, decimal
       fractions are permitted, and ‘‘never’’ is shorthand  for  an  extremely
       large  number.   The  first number gives the retention period: how long
       must pass after an article’s arrival  before  it  is  a  candidate  for
       expiry.   The  third  number gives the purge period: how long must pass
       after arrival before the article will be expired unconditionally.   The
       middle  number  gives  the  expiry  period: how long after an article’s
       arrival it is expired by default.   An  explicit  expiry  date  in  the
       article will override the expiry period but not the retention period or
       the purge period.  If the field contains only two numbers with  a  dash
       separating  them,  the  retention  period  defaults to 0.  If the field
       contains only a number, the retention period  defaults  to  0  and  the
       purge  period  defaults  to  ‘never’.   (But see below.)  The retention
       period must be less than the purge period, and the expiry  period  must
       lie between them.

       The fourth field is an archiving directory, or ‘@’ which indicates that
       the default archiving directory (see -a) should be used, or  ‘-’  which
       suppresses  archiving.   An  explicit  archiving  directory  (not  ‘@’)
       prefixed with ‘=’ means that articles  should  be  archived  into  that
       directory  itself;  normally  they  go  into subdirectories under it by
       newsgroup name, as in the current-news directory tree.  (E.g.,  article
       123  of comp.pc.drivel being archived into archive directory /exp would
       normally become /exp/comp/pc/drivel/123, but if the archiving directory
       was  given  as  ‘=/exp’  rather than ‘/exp’, it would become /exp/123.)
       Expire   creates   subdirectories   under   an   archiving    directory
       automatically,  but  will  not  create  the archiving directory itself.
       Archiving directories must be given as full pathnames.

       The first line of the control file which applies to a given article  is
       used  to  control its expiry.  It is an error for no line to apply; the
       last line should be something like ‘all x 7 -’ to ensure that at  least
       one line is always applicable.  Cross-posted articles are treated as if
       they were independently posted to each group.

       The retention and purge defaults  can  be  overridden  by  including  a
       bounds  line, one with the special first field /bounds/.  The retention
       and purge defaults for following lines will  be  those  of  the  bounds
       line.   The  defaults ‘‘stretch’’ as necessary to ensure that the purge
       period is never less than the expiry period and the retention period is
       never  greater  than  the  expiry period.  The other fields of a bounds
       line are ignored but must be present.

       Entries in the history file can be retained after  article  expiry,  to
       stop  a  late-arriving  copy  of  the article from being taken as a new
       article.  To arrange this, include a line with the special first  field
       /expired/;  this  line  then controls the expiry of history lines after
       the corresponding articles  expire.   Dates  are  still  measured  from
       article  arrival,  not  expiry.   The  other  fields of such a line are
       ignored but must be present.  It is strongly recommended  that  such  a
       line be included, and that it specify as long a time as practical.

       Command-line options are:

       -a dir    dir  is  the  default  archiving  directory; if no default is
                 given, the control file may  not  contain  any  ‘@’  archive-
                 directory fields.

       -p        print  an  ‘index’ line for each archived article, containing
                 its pathname, message ID, date received, and ‘Subject:’ line.

       -s        space  is  tight;  optimize  error recovery to minimize space
                 consumed rather than to leave as much evidence as possible.

       -F c      the subfield separator character in the middle history  field
                 is c rather than the normal ‘~’.

       -c        check  the format and consistency of the control file and the
                 active file, but do not do any expiring.

       -n nnnnn  set expire’s idea of the time to nnnnn (for testing).

       -t        print (on standard error) a shell-script-like description  of
                 what  would  be  done,  but  don’t  do it.  In the absence of
                 archiving,  all  output   lines   will   be   of   the   form
                 ‘‘remove name’’,   where  name  is  a  pathname  relative  to
                 /var/spool/news.  If an article is to be archived, this  will
                 be preceded (on the same line) by ‘‘copy name dir ; ’’, where
                 name is as in  remove  and  dir  is  an  archiving  directory
                 (including  any  ‘=’ prefix) as specified by the control file
                 or the -a option.

       -l        consider first filename in a history line to be the leader of
                 its  line,  to be expired only after all others have expired.
                 (Meant for use on obnoxious  systems  like  VMS  which  don’t
                 support real links.)

       -r        suppress  history  rebuild.   Mostly  for emergencies.  (This
                 leaves  the  history  file  out  of  date  and  larger   than
                 necessary,  but  improves  speed  and eliminates the need for
                 several megabytes of temporary storage.)

       -h        do not expire any article which would be archived if it  were
                 expired.   Mostly  for emergencies, so that expire can be run
                 (to delete articles in non-archived groups) even if space  is
                 short in archiving areas.

       -H historydir
                 the  history  file  and  its associated database files are in
                 historydir rather than  in  /var/lib/news.   (Useful  because
                 expire  needs  to  do  operations  that can’t be done through
                 symbolic links.)

       -v        verbose: report some statistics after termination.

       -g        report expiry dates that getindate(3) does not like.   Expire
                 ignores  such  dates,  treating  the  article as if it had no
                 explicit expiry date.

       -d        turn on (voluminous and cryptic) debugging output.

       Expire considers the middle field of a history line to consist  of  one
       or  more  subfields  separated  by ‘~’.  The first is the arrival date,
       which can be either an Internet-format human-readable date or a decimal
       seconds  count;  expire  leaves  this  field  unchanged.  The second—if
       present, non-null, and not ‘-’—is an explicit expiry date for the file,
       again  in either format, which expire will convert to a decimal seconds
       count as it  regenerates  the  history  file.   Subsequent  fields  are
       preserved but ignored.

       Doexpire  checks whether another doexpire is running, checks that there
       is enough disk space, invokes expire with any expireoptions  given  and
       with  /var/lib/news/explist  as  the  control file, then runs upact and
       expov (see newsoverview(8CN)), and reports any difficulties by  sending
       mail  via  report.   This  is  usually  better than just running expire
       directly.  If space is not adequate  for  archiving,  doexpire  reports
       this  and  invokes  expire  with the -h option.  If -r is not among the
       expireoptions, and  disk  space  is  persistently  inadequate  for  the
       temporaries  needed  for  history rebuilding, doexpire reports this and
       invokes expire with the -r option anyway.  -f suppresses this,  forcing
       expire  to  be  run  without  -r regardless of the space situation.  -e
       suppresses running of upact and expov, restricting doexpire to  running
       expire only.  -r implies -e.

       Expireiflow  checks  whether  there  are  at  least  minimum  megabytes
       available  for  articles,  and  invokes  doexpire  with  -r   and   the
       expireoptions (if any) if not.  This may be useful on systems which run
       close to the edge on disk space.

       Upact updates the active file to match the articles in  /var/spool/news
       (for  various  reasons, expire does not do this).  Normally, it updates
       the third field, and makes  sure  the  second  field  (which  relaynews
       updates  in  place  and  cannot expand) has a ‘0’ on the front.  The -p
       option suppresses all manipulation of the second field.  The -b  option
       causes  both  second  and  third  fields  to  be  rebuilt  based on the
       articles, for disaster recovery.  The -s option invokes  a  slower  but
       more  robust version of upact’s internal machinery, which may be needed
       if the output of the system’s ls command is broken in some way.   Upact
       builds  a  new  version  of the active file in active.tmp, and normally
       renames this to active  at  the  end;  the  -#  option  suppresses  the
       renaming, leaving the result in active.tmp for debugging or inspection.

       Upact forces the third field of the active file to  be  at  least  five
       digits,  for  backward  compatibility,  but  otherwise just makes it as
       large as necessary.  This field is never updated in place, so extending
       it to a larger number of digits is unnecessary.

       The  new  implementation  of  upact  supersedes  the  old  recovact and
       updatemin commands, and is much faster than the old upact.

FILES

       /var/lib/news/history   history file
       /var/lib/news/history.pagdbm database for history file
       /var/lib/news/history.dirdbm database for history file
       /var/lib/news/explist   expiry control file
       /var/lib/news/history.o history file as of last expiry
       /var/lib/news/history.n*new history file and dbm files abuilding
       /var/lib/news/LOCKexpiredoexpire’s lock file

SEE ALSO

       inews(1CN), dbm(3), newssys(5), relaynews(8CN)

HISTORY

       Written at U of Toronto by Henry Spencer, with contributions  by  Geoff
       Collyer.   The  idea  for  the  fast algorithm in upact came from Bernd
       Felsche of MetaPro Systems, although the final code is rather different
       from his.

BUGS

       Archiving  is  always  done by copying, never by linking.  This has the
       side  effect  that  cross-posted  articles  are  archived  as   several
       independent copies.

       The  -p  subject-finder  botches  continued header lines, although such
       lines are rare.

       One cannot  put  more  than  one  newsgroup  into  a  single  archiving
       directory  with the ‘=’ feature, since the article numbers will collide
       with each other and expire doesn’t do anything about this.   Note  that
       archiving  a  newsgroup  which has subgroups into an ‘=’ directory puts
       all the subgroups in the same directory as the parent!  (Specifying the
       group as ‘foo.bar,!foo.bar.all’ will avoid this.)

       Expire   uses   access(2)   to  test  for  the  presence  of  archiving
       directories, which can cause anomalies if it is  run  setuid  (normally
       it’s not).

       Expire  startup  time  is  proportional to the product of the number of
       entries in the control file and the number of lines in active.  It  can
       be significant for complex control files.

                                  19 Oct 1994                      EXPIRE(8cn)