Backup(3)                                                            Backup(3)

SYNOPSIS

   #include "V.h"

   Backup(name)
   char *name;

DESCRIPTION
   This routine "backs up" a file by renaming according to the current
   BACKUP  convention.  This is done recursively, of course, resulting
   in a series of files that are backups of the primary file.

   The BACKUP convention is determined by looking in the environment
   vector for "BACKUP", whose value is of the form:
      <n><c><s>
   where:
      <n> is the m number of backups (default: 8).
      <c> is a char to be added to the file name (default: '-').
      <s> is a suffix string, if desired (default: none).
   The recognized values for <c> are '-', '*', '#', '.' and ';' .   If
   '#'  is  used,  it is inserted as a prefix to the last field of the
   file, so for example "a/b/c" will be renamed to "a/b/#c". The other
   values  of <c> are added to the end of the file name, so "x/y" will
   be renamed to "x/y-".  If <n> is greated than 1,  multiple  backups
   are made by repeating the character.

   There are some special cases for the  suffix  string.   If  <s>  is
   numeric,  the  backup  convention  will  be  to  append  sequential
   numbers. For example, if BACKUP is ".4", "a/b" will be backed up to
   "a/b.1", and then to "a/b.2", etc. The number used will also be the
   limit to the number of backups, and overrides <n> if it is present.

   If the <s> suffix is non-numeric (such as ".bak"), <n> will be  set
   to 1, and only a single backup may be made by appending the suffix.

   The default BACKUP is "8-", which backs files up by appending up to
   8 hyphens.

   The ';n' backup style is like VMS's backup, but it isn't convenient
   on Unix systems, whose shells use ';' as a command terminator.

   The backup style may be  determined  or  altered  at  run  time  by
   calling  the  function  Bpopt("..."),  where  "..."  is the desired
   backup option.

EXAMPLES

   setenv BACKUP "5#"

   This will cause Backup("foo/bar") to rename  "foo/bar"  to  "foo/#bar",
   which  will  in  turn  be renamed to "foo/##bar" if it exists.  The
   longest name that this will produce will be "foo/#####bar".

   setenv BACKUP ".bak"

   This will do backups by appending ".bak" to the file name.  If  you
   call  Backup("xx")  and "xx.bak" already exists, it will disappear, and
   "xx" will be renamed to "xx.bak".

   setenv BACKUP ".3"

   This will do backups by appending "." and  a  number  to  the  file
   name.   The  file  "xx"  will  be  renamed to "xx.1"; "xx.1 will be
   renamed to "xx.2", and so on. If the filename already ends with '.'
   and a number, it will be backed up similarly, for up to 3 versions.

   setenv BACKUP 0

   This will disable backups, so that even if a script uses a  command
   like Rm or Ln, no backups will actually be made.  Use with care.

   unsetenv BACKUP
   setenv BACKUP '8-'

   This will give the default backup behavior, producing backups  with
   hyphens on the end of their names. This is especially convenient on
   Unix systems.  For example, the command
      rm *--
   will remove all but the latest backup copy of all files.

RETURN VALUE
   The return value is 0 for success; -1  means  failure  (with  errno
   showing  the reason for failure, as usual).  The only error code on
   most Unix systems is EPERM,  meaning  that  you  don't  have  write
   permission on the directory.

GLOBALS
   These are variables that might conflict with yours.   All  but  one
   have names that start with "bp".

   The global variable "backups" is the limit to the number of  backup
   copies  kept  (i.e.,  the  depth of recursion).  The default is -1,
   which means no limit.

   The global variable "bpfailed" is a count of the number of  renames
   that failed. It is possible for Backup() to report success and also
   increment bpfailed; this means that the named file was successfully
   renamed, but that some backup that existed could not be renamed.

   The global  variable  "bpstyle"  is  the  char  <c>;  the  variable
   "bpsuffix"  points  to  the  suffix string (if any), and "bpsufnum"
   contains the suffix limit for numeric suffixes.

   The global variable "preserve" is in common with the code  for  the
   cp  and  mv  commands;  it  is  a  flag  saying whether to preserve
   timestamps. It actually isn't used by Backup(), but is kept here to
   satisfy the linker.

   Note that Backup() is part of jc's audit/debug/verbose package, and
   you need at least the V.h header file and the libV.a archive to
   be able to compile and link. The function's "real" name is actually
   "backup",  as you might expect; Backup() is a macro to take care of
   the run-time arg properly.

BUGS
   On some Sys/V machines, it is wise to limit the number  of  backups
   to  a small number, because infinite recursion can occur due to the
   problem  with  open()  truncating  file  names   longer   than   14
   characters.