home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / gnu / elisp / elisp-18 < prev    next >
Encoding:
GNU Info File  |  1993-05-31  |  45.9 KB  |  1,174 lines
  1. This is Info file elisp, produced by Makeinfo-1.55 from the input file
  2. elisp.texi.
  3.  
  4.    This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for
  5. Emacs Version 19.
  6.  
  7.    Published by the Free Software Foundation, 675 Massachusetts Avenue,
  8. Cambridge, MA 02139 USA
  9.  
  10.    Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
  11.  
  12.    Permission is granted to make and distribute verbatim copies of this
  13. manual provided the copyright notice and this permission notice are
  14. preserved on all copies.
  15.  
  16.    Permission is granted to copy and distribute modified versions of
  17. this manual under the conditions for verbatim copying, provided that
  18. the entire resulting derived work is distributed under the terms of a
  19. permission notice identical to this one.
  20.  
  21.    Permission is granted to copy and distribute translations of this
  22. manual into another language, under the above conditions for modified
  23. versions, except that this permission notice may be stated in a
  24. translation approved by the Foundation.
  25.  
  26. 
  27. File: elisp,  Node: File Attributes,  Prev: Truenames,  Up: Information about Files
  28.  
  29. Other Information about Files
  30. -----------------------------
  31.  
  32.    This section describes the functions for getting detailed information
  33. about a file, other than its contents.  This information includes the
  34. mode bits that control access permission, the owner and group numbers,
  35. the number of names, the inode number, the size, and the times of access
  36. and modification.
  37.  
  38.  - Function: file-modes FILENAME
  39.      This function returns the mode bits of FILENAME, as an integer.
  40.      The mode bits are also called the file permissions, and they
  41.      specify access control in the usual Unix fashion.  If the
  42.      low-order bit is 1, then the file is executable by all users, if
  43.      the second lowest-order bit is 1, then the file is writable by all
  44.      users, etc.
  45.  
  46.      The highest value returnable is 4095 (7777 octal), meaning that
  47.      everyone has read, write, and execute permission, that the SUID bit
  48.      is set for both others and group, and that the sticky bit is set.
  49.  
  50.           (file-modes "~/junk/diffs")
  51.                => 492               ; Decimal integer.
  52.           (format "%o" 492)
  53.                => 754               ; Convert to octal.
  54.           
  55.           (set-file-modes "~/junk/diffs" 438)
  56.                => nil
  57.           
  58.           (format "%o" 438)
  59.                => 666               ; Convert to octal.
  60.           
  61.           % ls -l diffs
  62.             -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs
  63.  
  64.  - Function: file-nlinks FILENAME
  65.      This functions returns the number of names (i.e., hard links) that
  66.      file FILENAME has.  If the file does not exist, then this function
  67.      returns `nil'.  Note that symbolic links have no effect on this
  68.      function, because they are not considered to be names of the files
  69.      they link to.
  70.  
  71.           % ls -l foo*
  72.           -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo
  73.           -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo1
  74.           
  75.           (file-nlinks "foo")
  76.                => 2
  77.           (file-nlinks "doesnt-exist")
  78.                => nil
  79.  
  80.  - Function: file-attributes FILENAME
  81.      This function returns a list of attributes of file FILENAME.  If
  82.      the specified file cannot be opened, it returns `nil'.
  83.  
  84.      The elements of the list, in order, are:
  85.  
  86.        0. `t' for a directory, a string for a symbolic link (the name
  87.           linked to), or `nil' for a text file.
  88.  
  89.        1. The number of names the file has.  Alternate names, also
  90.           known as hard links, can be created by using the
  91.           `add-name-to-file' function (*note Changing File
  92.           Attributes::.).
  93.  
  94.        2. The file's UID.
  95.  
  96.        3. The file's GID.
  97.  
  98.        4. The time of last access, as a list of two integers.  The
  99.           first integer has the high-order 16 bits of time, the second
  100.           has the low 16 bits.  (This is similar to the value of
  101.           `current-time'; see *Note Time of Day::.)
  102.  
  103.        5. The time of last modification as a list of two integers (as
  104.           above).
  105.  
  106.        6. The time of last status change as a list of two integers (as
  107.           above).
  108.  
  109.        7. The size of the file in bytes.
  110.  
  111.        8. The file's modes, as a string of ten letters or dashes as in
  112.           `ls -l'.
  113.  
  114.        9. `t' if the file's GID would change if file were deleted and
  115.           recreated; `nil' otherwise.
  116.  
  117.       10. The file's inode number.
  118.  
  119.       11. The file system number of the file system that the file is
  120.           in.  This element together with the file's inode number, give
  121.           enough information to distinguish any two files on the
  122.           system--no two files can have the same values for both of
  123.           these numbers.
  124.  
  125.      For example, here are the file attributes for `files.texi':
  126.  
  127.           (file-attributes "files.texi")
  128.                =>  (nil
  129.                     1
  130.                     2235
  131.                     75
  132.                     (8489 20284)
  133.                     (8489 20284)
  134.                     (8489 20285)
  135.                     14906
  136.                     "-rw-rw-rw-"
  137.                     nil
  138.                     129500
  139.                     -32252)
  140.  
  141.      and here is how the result is interpreted:
  142.  
  143.     `nil'
  144.           is neither a directory nor a symbolic link.
  145.  
  146.     `1'
  147.           has only one name (the name `files.texi' in the current
  148.           default directory).
  149.  
  150.     `2235'
  151.           is owned by the user with UID 2235.
  152.  
  153.     `75'
  154.           is in the group with GID 75.
  155.  
  156.     `(8489 20284)'
  157.           was last accessed on Aug 19 00:09.  Unfortunately, you cannot
  158.           convert this number into a time string in Emacs.
  159.  
  160.     `(8489 20284)'
  161.           was last modified on Aug 19 00:09.
  162.  
  163.     `(8489 20285)'
  164.           last had its inode changed on Aug 19 00:09.
  165.  
  166.     `14906'
  167.           is 14906 characters long.
  168.  
  169.     `"-rw-rw-rw-"'
  170.           has a mode of read and write access for the owner, group, and
  171.           world.
  172.  
  173.     `nil'
  174.           would retain the same GID if it were recreated.
  175.  
  176.     `129500'
  177.           has an inode number of 129500.
  178.  
  179.     `-32252'
  180.           is on file system number -32252.
  181.  
  182. 
  183. File: elisp,  Node: Contents of Directories,  Next: Create/Delete Dirs,  Prev: Information about Files,  Up: Files
  184.  
  185. Contents of Directories
  186. =======================
  187.  
  188.    A directory is a kind of file that contains other files entered under
  189. various names.  Directories are a feature of the file system.
  190.  
  191.    Emacs can list the names of the files in a directory as a Lisp list,
  192. or display the names in a buffer using the `ls' shell command.  In the
  193. latter case, it can optionally display information about each file,
  194. depending on the value of switches passed to the `ls' command.
  195.  
  196.  - Function: directory-files DIRECTORY &optional FULL-NAME MATCH-REGEXP
  197.           NOSORT
  198.      This function returns a list of the names of the files in the
  199.      directory DIRECTORY.  By default, the list is in alphabetical
  200.      order.
  201.  
  202.      If FULL-NAME is non-`nil', the function returns the files'
  203.      absolute file names.  Otherwise, it returns just the names
  204.      relative to the specified directory.
  205.  
  206.      If MATCH-REGEXP is non-`nil', this function returns only those
  207.      file names that contain that regular expression--the other file
  208.      names are discarded from the list.
  209.  
  210.      If NOSORT is non-`nil', that inhibits sorting the list, so you get
  211.      the file names in no particular order.  Use this if you want the
  212.      utmost possible speed and don't care what order the files are
  213.      processed in.  If the order of processing is visible to the user,
  214.      then the user will probably be happier if you do sort the names.
  215.  
  216.           (directory-files "~lewis")
  217.                => ("#foo#" "#foo.el#" "." ".."
  218.                    "dired-mods.el" "files.texi"
  219.                    "files.texi.~1~")
  220.  
  221.      An error is signaled if DIRECTORY is not the name of a directory
  222.      that can be read.
  223.  
  224.  - Function: file-name-all-versions FILE DIRNAME
  225.      This function returns a list of all versions of the file named
  226.      FILE in directory DIRNAME.
  227.  
  228.  - Function: insert-directory FILE SWITCHES &optional WILDCARD
  229.           FULL-DIRECTORY-P
  230.      This function inserts a directory listing for directory DIR,
  231.      formatted according to SWITCHES.  It leaves point after the
  232.      inserted text.
  233.  
  234.      The argument DIR may be either a directory name or a file
  235.      specification including wildcard characters.  If WILDCARD is
  236.      non-`nil', that means treat FILE as a file specification with
  237.      wildcards.
  238.  
  239.      If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
  240.      and switches do not contain `d', so that a full listing is
  241.      expected.
  242.  
  243.      This function works by running a directory listing program whose
  244.      name is in the variable `insert-directory-program'.  If WILDCARD is
  245.      non-`nil', it also runs the shell specified by `shell-file-name',
  246.      to expand the wildcards.
  247.  
  248.  - Variable: insert-directory-program
  249.      This variable's value is the program to run to generate a
  250.      directory listing for the function `insert-directory'.
  251.  
  252. 
  253. File: elisp,  Node: Create/Delete Dirs,  Next: Changing File Attributes,  Prev: Contents of Directories,  Up: Files
  254.  
  255. Creating and Deleting Directories
  256. =================================
  257.  
  258.  - Function: make-directory DIRNAME
  259.      This function creates a directory named DIRNAME.
  260.  
  261.  - Function: delete-directory DIRNAME
  262.      This function deletes the directory named DIRNAME.  The function
  263.      `delete-file' does not work for files that are directories; you
  264.      must use `delete-directory' in that case.
  265.  
  266. 
  267. File: elisp,  Node: Changing File Attributes,  Next: File Names,  Prev: Create/Delete Dirs,  Up: Files
  268.  
  269. Changing File Names and Attributes
  270. ==================================
  271.  
  272.    The functions in this section rename, copy, delete, link, and set the
  273. modes of files.
  274.  
  275.    In the functions that have an argument NEWNAME, if a file by the
  276. name of NEWNAME already exists, the actions taken depend on the value
  277. of the argument OK-IF-ALREADY-EXISTS:
  278.  
  279.    * A `file-already-exists' error is signaled if OK-IF-ALREADY-EXISTS
  280.      is `nil'.
  281.  
  282.    * Confirmation is requested if OK-IF-ALREADY-EXISTS is a number.
  283.  
  284.    * No confirmation is requested if OK-IF-ALREADY-EXISTS is any other
  285.      value, in which case the old file is removed.
  286.  
  287.  - Function: add-name-to-file OLDNAME NEWNAME &optional
  288.           OK-IF-ALREADY-EXISTS
  289.      This function gives the file named OLDNAME the additional name
  290.      NEWNAME.  This means that NEWNAME becomes a new "hard link" to
  291.      OLDNAME.
  292.  
  293.      In the first part of the following example, we list two files,
  294.      `foo' and `foo3'.
  295.  
  296.           % ls -l fo*
  297.           -rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
  298.           -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
  299.  
  300.      Then we evaluate the form `(add-name-to-file "~/lewis/foo"
  301.      "~/lewis/foo2")'.  Again we list the files.  This shows two names,
  302.      `foo' and `foo2'.
  303.  
  304.           (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
  305.                => nil
  306.           
  307.           % ls -l fo*
  308.           -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
  309.           -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
  310.           -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
  311.  
  312.      Finally, we evaluate the following:
  313.  
  314.           (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
  315.  
  316.      and list the files again.  Now there are three names for one file:
  317.      `foo', `foo2', and `foo3'.  The old contents of `foo3' are lost.
  318.  
  319.           (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
  320.                => nil
  321.           
  322.           % ls -l fo*
  323.           -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
  324.           -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
  325.           -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3
  326.  
  327.      This function is meaningless on VMS, where multiple names for one
  328.      file are not allowed.
  329.  
  330.      See also `file-nlinks' in *Note File Attributes::.
  331.  
  332.  - Command: rename-file FILENAME NEWNAME &optional OK-IF-ALREADY-EXISTS
  333.      This command renames the file FILENAME as NEWNAME.
  334.  
  335.      If FILENAME has additional names aside from FILENAME, it continues
  336.      to have those names.  In fact, adding the name NEWNAME with
  337.      `add-name-to-file' and then deleting FILENAME has the same effect
  338.      as renaming, aside from momentary intermediate states.
  339.  
  340.      In an interactive call, this function prompts for FILENAME and
  341.      NEWNAME in the minibuffer; also, it requests confirmation if
  342.      NEWNAME already exists.
  343.  
  344.  - Command: copy-file OLDNAME NEWNAME &optional OK-IF-EXISTS TIME
  345.      This command copies the file OLDNAME to NEWNAME.  An error is
  346.      signaled if OLDNAME does not exist.
  347.  
  348.      If TIME is non-`nil', then this functions gives the new file the
  349.      same last-modified time that the old one has.  (This works on only
  350.      some operating systems.)
  351.  
  352.      In an interactive call, this function prompts for FILENAME and
  353.      NEWNAME in the minibuffer; also, it requests confirmation if
  354.      NEWNAME already exists.
  355.  
  356.  - Command: delete-file FILENAME
  357.      This command deletes the file FILENAME, like the shell command `rm
  358.      FILENAME'.  If the file has multiple names, it continues to exist
  359.      under the other names.
  360.  
  361.      A suitable kind of `file-error' error is signaled if the file does
  362.      not exist, or is not deletable.  (In Unix, a file is deletable if
  363.      its directory is writable.)
  364.  
  365.      See also `delete-directory' in *Note Create/Delete Dirs::.
  366.  
  367.  - Command: make-symbolic-link FILENAME NEWNAME &optional OK-IF-EXISTS
  368.      This command makes a symbolic link to FILENAME, named NEWNAME.
  369.      This is like the shell command `ln -s FILENAME NEWNAME'.
  370.  
  371.      In an interactive call, FILENAME and NEWNAME are read in the
  372.      minibuffer, and OK-IF-EXISTS is set to the numeric prefix argument.
  373.  
  374.  - Function: define-logical-name VARNAME STRING
  375.      This function defines the logical name NAME to have the value
  376.      STRING.  It is available only on VMS.
  377.  
  378.  - Function: set-file-modes FILENAME MODE
  379.      This function sets mode bits of FILENAME to MODE (which must be an
  380.      integer).  Only the 12 low bits of MODE are used.
  381.  
  382.  - Function: set-default-file-modes MODE
  383.      This function sets the default file protection for new files
  384.      created by Emacs and its subprocesses.  Every file created with
  385.      Emacs initially has this protection.  On Unix, the default
  386.      protection is the bitwise complement of the "umask" value.
  387.  
  388.      The argument MODE must be an integer.  Only the 9 low bits of MODE
  389.      are used.
  390.  
  391.      Saving a modified version of an existing file does not count as
  392.      creating the file; it does not change the file's mode, and does
  393.      not use the default file protection.
  394.  
  395.  - Function: default-file-modes
  396.      This function returns the current default protection value.
  397.  
  398. 
  399. File: elisp,  Node: File Names,  Next: Magic File Names,  Prev: Changing File Attributes,  Up: Files
  400.  
  401. File Names
  402. ==========
  403.  
  404.    Files are generally referred to by their names, in Emacs as
  405. elsewhere.  File names in Emacs are represented as strings.  The
  406. functions that operate on a file all expect a file name argument.
  407.  
  408.    In addition to operating on files themselves, Emacs Lisp programs
  409. often need to operate on the names; i.e., to take them apart and to use
  410. part of a name to construct related file names.  This section describes
  411. how to manipulate file names.
  412.  
  413.    The functions in this section do not actually access files, so they
  414. can operate on file names that do not refer to an existing file or
  415. directory.
  416.  
  417.    On VMS, all these functions understand both VMS file name syntax and
  418. Unix syntax.  This is so that all the standard Lisp libraries can
  419. specify file names in Unix syntax and work properly on VMS without
  420. change.
  421.  
  422. * Menu:
  423.  
  424. * File Name Components::  The directory part of a file name, and the rest.
  425. * Directory Names::       A directory's name as a directory
  426.                             is different from its name as a file.
  427. * Relative File Names::   Some file names are relative to a current directory.
  428. * File Name Expansion::   Converting relative file names to absolute ones.
  429. * Unique File Names::     Generating names for temporary files.
  430. * File Name Completion::  Finding the completions for a given file name.
  431.  
  432. 
  433. File: elisp,  Node: File Name Components,  Next: Directory Names,  Up: File Names
  434.  
  435. File Name Components
  436. --------------------
  437.  
  438.    The operating system groups files into directories.  To specify a
  439. file, you must specify the directory, and the file's name in that
  440. directory.  Therefore, a file name in Emacs is considered to have two
  441. main parts: the "directory name" part, and the "nondirectory" part (or
  442. "file name within the directory").  Either part may be empty.
  443. Concatenating these two parts reproduces the original file name.
  444.  
  445.    On Unix, the directory part is everything up to and including the
  446. last slash; the nondirectory part is the rest.  The rules in VMS syntax
  447. are complicated.
  448.  
  449.    For some purposes, the nondirectory part is further subdivided into
  450. the name proper and the "version number".  On Unix, only backup files
  451. have version numbers in their names; on VMS, every file has a version
  452. number, but most of the time the file name actually used in Emacs omits
  453. the version number.  Version numbers are found mostly in directory
  454. lists.
  455.  
  456.  - Function: file-name-directory FILENAME
  457.      This function returns the directory part of FILENAME (or `nil' if
  458.      FILENAME does not include a directory part).  On Unix, the
  459.      function returns a string ending in a slash.  On VMS, it returns a
  460.      string ending in one of the three characters `:', `]', or `>'.
  461.  
  462.           (file-name-directory "lewis/foo")  ; Unix example
  463.                => "lewis/"
  464.           (file-name-directory "foo")        ; Unix example
  465.                => nil
  466.           (file-name-directory "[X]FOO.TMP") ; VMS example
  467.                => "[X]"
  468.  
  469.  - Function: file-name-nondirectory FILENAME
  470.      This function returns the nondirectory part of FILENAME.
  471.  
  472.           (file-name-nondirectory "lewis/foo")
  473.                => "foo"
  474.           (file-name-nondirectory "foo")
  475.                => "foo"
  476.           ;; The following example is accurate only on VMS.
  477.           (file-name-nondirectory "[X]FOO.TMP")
  478.                => "FOO.TMP"
  479.  
  480.  - Function: file-name-sans-versions FILENAME
  481.      This function returns FILENAME without any file version numbers,
  482.      backup version numbers, or trailing tildes.
  483.  
  484.           (file-name-sans-versions "~rms/foo.~1~")
  485.                => "~rms/foo"
  486.           (file-name-sans-versions "~rms/foo~")
  487.                => "~rms/foo"
  488.           (file-name-sans-versions "~rms/foo")
  489.                => "~rms/foo"
  490.           ;; The following example applies to VMS only.
  491.           (file-name-sans-versions "foo;23")
  492.                => "foo"
  493.  
  494. 
  495. File: elisp,  Node: Directory Names,  Next: Relative File Names,  Prev: File Name Components,  Up: File Names
  496.  
  497. Directory Names
  498. ---------------
  499.  
  500.    A "directory name" is the name of a directory.  A directory is a
  501. kind of file, and it has a file name, which is related to the directory
  502. name but not identical to it.  (This is not quite the same as the usual
  503. Unix terminology.)  These two different names for the same entity are
  504. related by a syntactic transformation.  On Unix, this is simple: a
  505. directory name ends in a slash, whereas the directory's name as a file
  506. lacks that slash.  On VMS, the relationship is more complicated.
  507.  
  508.    The difference between a directory name and its name as a file is
  509. subtle but crucial.  When an Emacs variable or function argument is
  510. described as being a directory name, a file name of a directory is not
  511. acceptable.
  512.  
  513.    These two functions take a single argument, FILENAME, which must be
  514. a string.  Environment variable substitutions such as `$HOME', and the
  515. symbols `~', and `..', are *not* expanded.  Use `expand-file-name' or
  516. `substitute-in-file-name' for that (*note File Name Expansion::.).
  517.  
  518.  - Function: file-name-as-directory FILENAME
  519.      This function returns a string representing FILENAME in a form
  520.      that the operating system will interpret as the name of a
  521.      directory.  In Unix, this means that a slash is appended to the
  522.      string.  On VMS, the function converts a string of the form
  523.      `[X]Y.DIR.1' to the form `[X.Y]'.
  524.  
  525.           (file-name-as-directory "~rms/lewis")
  526.                => "~rms/lewis/"
  527.  
  528.  - Function: directory-file-name DIRNAME
  529.      This function returns a string representing DIRNAME in a form that
  530.      the operating system will interpret as the name of a file.  On
  531.      Unix, this means removing a final slash from the string.  On VMS,
  532.      the function converts a string of the form `[X.Y]' to `[X]Y.DIR.1'.
  533.  
  534.           (directory-file-name "~lewis/")
  535.                => "~lewis"
  536.  
  537.    Directory name abbreviations are useful for directories that are
  538. normally accessed through symbolic links.  Sometimes the users recognize
  539. primarily the link's name as "the name" of the directory, and find it
  540. annoying to see the directory's "real" name.  If you define the link
  541. name as an abbreviation for the "real" name, Emacs shows users the
  542. abbreviation instead.
  543.  
  544.    If you wish to convert a directory name to its abbreviation, use this
  545. function:
  546.  
  547.  - Function: abbreviate-file-name DIRNAME
  548.      This function applies abbreviations from `directory-abbrev-alist'
  549.      to its argument, and substitutes `~' for the user's home directory.
  550.  
  551.  - Variable: directory-abbrev-alist
  552.      The variable `directory-abbrev-alist' contains an alist of
  553.      abbreviations to use for file directories.  Each element has the
  554.      form `(FROM . TO)', and says to replace FROM with TO when it
  555.      appears in a directory name.  The FROM string is actually a
  556.      regular expression; it should always start with `^'.  The function
  557.      `abbreviate-file-name' performs these substitutions.
  558.  
  559.      You can set this variable in `site-init.el' to describe the
  560.      abbreviations appropriate for your site.
  561.  
  562.      Here's an example, from a system on which file system `/home/fsf'
  563.      and so on are normally accessed through symbolic links named `/fsf'
  564.      and so on.
  565.  
  566.           (("^/home/fsf" . "/fsf")
  567.            ("^/home/gp" . "/gp")
  568.            ("^/home/gd" . "/gd"))
  569.  
  570. 
  571. File: elisp,  Node: Relative File Names,  Next: File Name Expansion,  Prev: Directory Names,  Up: File Names
  572.  
  573. Absolute and Relative File Names
  574. --------------------------------
  575.  
  576.    All the directories in the file system form a tree starting at the
  577. root directory.  A file name can specify all the directory names
  578. starting from the root of the tree; then it is called an "absolute"
  579. file name.  Or it can specify the position of the file in the tree
  580. relative to a default directory; then it is called an "relative" file
  581. name.  On Unix, an absolute file name starts with a slash or a tilde
  582. (`~'), and a relative one does not.  The rules on VMS are complicated.
  583.  
  584.  - Function: file-name-absolute-p FILENAME
  585.      This function returns `t' if file FILENAME is an absolute file
  586.      name, `nil' otherwise.  On VMS, this function understands both
  587.      Unix syntax and VMS syntax.
  588.  
  589.           (file-name-absolute-p "~rms/foo")
  590.                => t
  591.           (file-name-absolute-p "rms/foo")
  592.                => nil
  593.           (file-name-absolute-p "/user/rms/foo")
  594.                => t
  595.  
  596. 
  597. File: elisp,  Node: File Name Expansion,  Next: Unique File Names,  Prev: Relative File Names,  Up: File Names
  598.  
  599. Functions that Expand Filenames
  600. -------------------------------
  601.  
  602.    "Expansion" of a file name means converting a relative file name to
  603. an absolute one.  Since this is done relative to a default directory,
  604. you must specify the default directory name as well as the file name to
  605. be expanded.  Expansion also simplifies file names by eliminating
  606. redundancies such as `./' and `NAME/../'.
  607.  
  608.  - Function: expand-file-name FILENAME &optional DIRECTORY
  609.      This function converts FILENAME to an absolute file name.  If
  610.      DIRECTORY is supplied, it is the directory to start with if
  611.      FILENAME is relative.  (The value of DIRECTORY should itself be an
  612.      absolute, expanded file name; it should not start with `~'.)
  613.      Otherwise, the current buffer's value of `default-directory' is
  614.      used.  For example:
  615.  
  616.           (expand-file-name "foo")
  617.                => "/xcssun/users/rms/lewis/foo"
  618.           (expand-file-name "../foo")
  619.                => "/xcssun/users/rms/foo"
  620.           (expand-file-name "foo" "/usr/spool/")
  621.                => "/usr/spool/foo"
  622.           (expand-file-name "$HOME/foo")
  623.                => "/xcssun/users/rms/lewis/$HOME/foo"
  624.  
  625.      Filenames containing `.' or `..' are simplified to their canonical
  626.      form:
  627.  
  628.           (expand-file-name "bar/../foo")
  629.                => "/xcssun/users/rms/lewis/foo"
  630.  
  631.      `~/' is expanded into the user's home directory.  A `/' or `~'
  632.      following a `/' is taken to be the start of an absolute file name
  633.      that overrides what precedes it, so everything before that `/' or
  634.      `~' is deleted.  For example:
  635.  
  636.           (expand-file-name
  637.            "/a1/gnu//usr/local/lib/emacs/etc/MACHINES")
  638.                => "/usr/local/lib/emacs/etc/MACHINES"
  639.           (expand-file-name "/a1/gnu/~/foo")
  640.                => "/xcssun/users/rms/foo"
  641.  
  642.      In both cases, `/a1/gnu/' is discarded because an absolute file
  643.      name follows it.
  644.  
  645.      Note that `expand-file-name' does *not* expand environment
  646.      variables; that is done only by `substitute-in-file-name'.
  647.  
  648.  - Function: file-relative-name FILENAME DIRECTORY
  649.      This function does the inverse of expansion--it tries to return a
  650.      relative name which is equivalent to FILENAME when interpreted
  651.      relative to DIRECTORY.  (If such a relative name would be longer
  652.      than the absolute name, it returns the absolute name instead.)
  653.  
  654.           (file-relative-name "/foo/bar" "/foo/")
  655.                => "bar")
  656.           (file-relative-name "/foo/bar" "/hack/")
  657.                => "/foo/bar")
  658.  
  659.  - Variable: default-directory
  660.      The value of this buffer-local variable is the default directory
  661.      for the current buffer.  It is local in every buffer.
  662.      `expand-file-name' uses the default directory when its second
  663.      argument is `nil'.
  664.  
  665.      On Unix systems, the value is always a string ending with a slash.
  666.  
  667.           default-directory
  668.                => "/user/lewis/manual/"
  669.  
  670.  - Function: substitute-in-file-name FILENAME
  671.      This function replaces environment variables names in FILENAME
  672.      with the values to which they are set by the operating system.
  673.      Following standard Unix shell syntax, `$' is the prefix to
  674.      substitute an environment variable value.
  675.  
  676.      The environment variable name is the series of alphanumeric
  677.      characters (including underscores) that follow the `$'.  If the
  678.      character following the `$' is a `{', then the variable name is
  679.      everything up to the matching `}'.
  680.  
  681.      Here we assume that the environment variable `HOME', which holds
  682.      the user's home directory name, has the value `/xcssun/users/rms'.
  683.  
  684.           (substitute-in-file-name "$HOME/foo")
  685.                => "/xcssun/users/rms/foo"
  686.  
  687.      If a `~' or a `/' appears following a `/', after substitution,
  688.      everything before the following `/' is discarded:
  689.  
  690.           (substitute-in-file-name "bar/~/foo")
  691.                => "~/foo"
  692.           (substitute-in-file-name "/usr/local/$HOME/foo")
  693.                => "/xcssun/users/rms/foo"
  694.  
  695.      On VMS, `$' substitution is not done, so this function does nothing
  696.      on VMS except discard superfluous initial components as shown
  697.      above.
  698.  
  699. 
  700. File: elisp,  Node: Unique File Names,  Next: File Name Completion,  Prev: File Name Expansion,  Up: File Names
  701.  
  702. Generating Unique File Names
  703. ----------------------------
  704.  
  705.    Some programs need to write temporary files.  Here is the usual way
  706. to construct a name for such a file:
  707.  
  708.      (make-temp-name (concat "/tmp/" NAME-OF-APPLICATION))
  709.  
  710. Here we use the directory `/tmp/' because that is the standard place on
  711. Unix for temporary files.  The job of `make-temp-name' is to prevent
  712. two different users or two different jobs from trying to use the same
  713. name.
  714.  
  715.  - Function: make-temp-name STRING
  716.      This function generates string that can be used as a unique name.
  717.      The name starts with the prefix STRING, and ends with a number that
  718.      is different in each Emacs job.
  719.  
  720.           (make-temp-name "/tmp/foo")
  721.                => "/tmp/foo021304"
  722.  
  723.      To prevent conflicts among different application libraries run in
  724.      the same Emacs, each application should have its own STRING.  The
  725.      number added to the end of the name distinguishes between the same
  726.      application running in different Emacs jobs.
  727.  
  728. 
  729. File: elisp,  Node: File Name Completion,  Prev: Unique File Names,  Up: File Names
  730.  
  731. File Name Completion
  732. --------------------
  733.  
  734.    This section describes low-level subroutines for completing a file
  735. name.  For other completion functions, see *Note Completion::.
  736.  
  737.  - Function: file-name-all-completions PARTIAL-FILENAME DIRECTORY
  738.      This function returns a list of all possible completions for a file
  739.      whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
  740.      The order of the completions is the order of the files in the
  741.      directory, which is unpredictable and conveys no useful
  742.      information.
  743.  
  744.      The argument PARTIAL-FILENAME must be a file name containing no
  745.      directory part and no slash.  The current buffer's default
  746.      directory is prepended to DIRECTORY, if DIRECTORY is not an
  747.      absolute file name.
  748.  
  749.      In the following example, suppose that the current default
  750.      directory, `~rms/lewis', has five files whose names begin with `f':
  751.      `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
  752.  
  753.           (file-name-all-completions "f" "")
  754.                => ("foo" "file~" "file.c.~2~"
  755.                           "file.c.~1~" "file.c")
  756.           
  757.           (file-name-all-completions "fo" "")
  758.                => ("foo")
  759.  
  760.  - Function: file-name-completion FILENAME DIRECTORY
  761.      This function completes the file name FILENAME in directory
  762.      DIRECTORY.  It returns the longest prefix common to all file names
  763.      in directory DIRECTORY that start with FILENAME.
  764.  
  765.      If only one match exists and FILENAME matches it exactly, the
  766.      function returns `t'.  The function returns `nil' if directory
  767.      DIRECTORY contains no name starting with FILENAME.
  768.  
  769.      In the following example, suppose that the current default
  770.      directory has five files whose names begin with `f': `foo',
  771.      `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
  772.  
  773.           (file-name-completion "fi" "")
  774.                => "file"
  775.           
  776.           (file-name-completion "file.c.~1" "")
  777.                => "file.c.~1~"
  778.           
  779.           (file-name-completion "file.c.~1~" "")
  780.                => t
  781.           
  782.           (file-name-completion "file.c.~3" "")
  783.                => nil
  784.  
  785.  - User Option: completion-ignored-extensions
  786.      `file-name-completion' usually ignores file names that end in any
  787.      string in this list.  It does not ignore them when all the possible
  788.      completions end in one of these suffixes or when a buffer showing
  789.      all possible completions is displayed.
  790.  
  791.      A typical value might look like this:
  792.  
  793.           completion-ignored-extensions
  794.                => (".o" ".elc" "~" ".dvi")
  795.  
  796. 
  797. File: elisp,  Node: Magic File Names,  Prev: File Names,  Up: Files
  798.  
  799. Making Certain File Names "Magic"
  800. =================================
  801.  
  802.    You can implement special handling for certain file names.  This is
  803. called making those names "magic".  You must supply a regular
  804. expression to define the class of names (all those which match the
  805. regular expression), plus a handler that implements all the primitive
  806. Emacs file operations for file names that do match.
  807.  
  808.    The value of `file-name-handler-alist' is a list of handlers,
  809. together with regular expressions that decide when to apply each
  810. handler.  Each element has this form:
  811.  
  812.      (REGEXP . HANDLER)
  813.  
  814. All the Emacs primitives for file access and file name transformation
  815. check the given file name against `file-name-handler-alist'.  If the
  816. file name matches REGEXP, the primitives handle that file by calling
  817. HANDLER.
  818.  
  819.    The first argument given to HANDLER is the name of the primitive;
  820. the remaining arguments are the arguments that were passed to that
  821. operation.  (The first of these arguments is typically the file name
  822. itself.)  For example, if you do this:
  823.  
  824.      (file-exists-p FILENAME)
  825.  
  826. and FILENAME has handler HANDLER, then HANDLER is called like this:
  827.  
  828.      (funcall HANDLER 'file-exists-p FILENAME)
  829.  
  830.    Here are the operations that you can handle for a magic file name:
  831.  
  832. `add-name-to-file', `copy-file', `delete-directory',
  833. `delete-file', `directory-file-name', `directory-files',
  834. `dired-compress-file', `dired-uncache',
  835. `expand-file-name', `file-accessible-directory-p',
  836. `file-attributes', `file-directory-p',
  837. `file-executable-p', `file-exists-p', `file-local-copy',
  838. `file-modes', `file-name-all-completions',
  839. `file-name-as-directory', `file-name-completion',
  840. `file-name-directory', `file-name-nondirectory',
  841. `file-name-sans-versions', `file-newer-than-file-p',
  842. `file-readable-p', `file-symlink-p', `file-writable-p',
  843. `insert-directory', `insert-file-contents',
  844. `make-directory', `make-symbolic-link', `rename-file',
  845. `set-file-modes', `set-visited-file-modtime',
  846. `unhandled-file-name-directory',
  847. `verify-visited-file-modtime', `write-region'.
  848.  
  849.    The handler function must handle all of the above operations, and
  850. possibly others to be added in the future.  Therefore, it should always
  851. reinvoke the ordinary Lisp primitive when it receives an operation it
  852. does not recognize.  Here's one way to do this:
  853.  
  854.      (defun my-file-handler (operation &rest args)
  855.        ;; First check for the specific operations
  856.        ;; that we have special handling for.
  857.        (cond ((eq operation 'insert-file-contents) ...)
  858.              ((eq operation 'write-region) ...)
  859.              ...
  860.              ;; Handle any operation we don't know about.
  861.              (t (let (file-name-handler-alist)
  862.                   (apply operation args)))))
  863.  
  864.  - Function: find-file-name-handler FILE
  865.      This function returns the handler function for file name FILE, or
  866.      `nil' if there is none.
  867.  
  868.  - Function: file-local-copy FILENAME
  869.      This function copies file FILENAME to the local site, if it isn't
  870.      there already.  If FILENAME specifies a "magic" file name which
  871.      programs outside Emacs cannot directly read or write, this copies
  872.      the contents to an ordinary file and returns that file's name.
  873.  
  874.      If FILENAME is an ordinary file name, not magic, then this function
  875.      does nothing and returns `nil'.
  876.  
  877.  - Function: unhandled-file-name-directory FILENAME
  878.      This function returns the name of a directory that is not magic.
  879.      It uses the directory part of FILENAME if that is not magic.
  880.      Otherwise, it asks the handler what to do.
  881.  
  882.      This is used for running a subprocess; any subprocess must have a
  883.      non-magic directory to serve as its current directory.
  884.  
  885. 
  886. File: elisp,  Node: Backups and Auto-Saving,  Next: Buffers,  Prev: Files,  Up: Top
  887.  
  888. Backups and Auto-Saving
  889. ***********************
  890.  
  891.    Backup files and auto-save files are two methods by which Emacs tries
  892. to protect the user from the consequences of crashes or of the user's
  893. own errors.  Auto-saving preserves the text from earlier in the current
  894. editing session; backup files preserve file contents prior to the
  895. current session.
  896.  
  897. * Menu:
  898.  
  899. * Backup Files::   How backup files are made; how their names are chosen.
  900. * Auto-Saving::    How auto-save files are made; how their names are chosen.
  901. * Reverting::      `revert-buffer', and how to customize what it does.
  902.  
  903. 
  904. File: elisp,  Node: Backup Files,  Next: Auto-Saving,  Prev: Backups and Auto-Saving,  Up: Backups and Auto-Saving
  905.  
  906. Backup Files
  907. ============
  908.  
  909.    A "backup file" is a copy of the old contents of a file you are
  910. editing.  Emacs makes a backup file the first time you save a buffer
  911. into its visited file.  Normally, this means that the backup file
  912. contains the contents of the file as it was before the current editing
  913. session.  The contents of the backup file normally remain unchanged once
  914. it exists.
  915.  
  916.    Backups are usually made by renaming the visited file to a new name.
  917. Optionally, you can specify that backup files should be made by copying
  918. the visited file.  This choice makes a difference for files with
  919. multiple names; it also can affect whether the edited file remains owned
  920. by the original owner or becomes owned by the user editing it.
  921.  
  922.    By default, Emacs makes a single backup file for each file edited.
  923. You can alternatively request numbered backups; then each new backup
  924. file gets a new name.  You can delete old numbered backups when you
  925. don't want them any more, or Emacs can delete them automatically.
  926.  
  927. * Menu:
  928.  
  929. * Making Backups::     How Emacs makes backup files, and when.
  930. * Rename or Copy::     Two alternatives: renaming the old file or copying it.
  931. * Numbered Backups::   Keeping multiple backups for each source file.
  932. * Backup Names::       How backup file names are computed; customization.
  933.  
  934. 
  935. File: elisp,  Node: Making Backups,  Next: Rename or Copy,  Prev: Backup Files,  Up: Backup Files
  936.  
  937. Making Backup Files
  938. -------------------
  939.  
  940.  - Function: backup-buffer
  941.      This function makes a backup of the file visited by the current
  942.      buffer, if appropriate.  It is called by `save-buffer' before
  943.      saving the buffer the first time.
  944.  
  945.  - Variable: buffer-backed-up
  946.      This buffer-local variable indicates whether this buffer's file has
  947.      been backed up on account of this buffer.  If it is non-`nil', then
  948.      the backup file has been written.  Otherwise, the file should be
  949.      backed up when it is next saved (if backup files are enabled).
  950.      This is a permanent local; `kill-local-variables' does not alter
  951.      it.
  952.  
  953.  - User Option: make-backup-files
  954.      This variable determines whether or not to make backup files.  If
  955.      it is non-`nil', then Emacs creates a backup of each file when it
  956.      is saved for the first time.
  957.  
  958.      The following example shows how to change the `make-backup-files'
  959.      variable only in the `RMAIL' buffer and not elsewhere.  Setting it
  960.      `nil' stops Emacs from making backups of the `RMAIL' file, which
  961.      may save disk space.  (You would put this code in your `.emacs'
  962.      file.)
  963.  
  964.           (add-hook 'rmail-mode-hook
  965.                     (function (lambda ()
  966.                                 (make-local-variable
  967.                                  'make-backup-files)
  968.                                 (setq make-backup-files nil))))
  969.  
  970.  - Variable: backup-enable-predicate
  971.      This variable's value is a function to be called on certain
  972.      occasions to decide whether a there should be backup files for
  973.      file name FILENAME.  If it returns `nil', backups are disabled.
  974.      Otherwise, backups are enabled (if `make-backup-files' is true).
  975.  
  976. 
  977. File: elisp,  Node: Rename or Copy,  Next: Numbered Backups,  Prev: Making Backups,  Up: Backup Files
  978.  
  979. Backup by Renaming or by Copying?
  980. ---------------------------------
  981.  
  982.    There are two ways that Emacs can make a backup file:
  983.  
  984.    * Emacs can rename the original file so that it becomes a backup
  985.      file, and then write the buffer being saved into a new file.
  986.      After this procedure, any other names (i.e., hard links) of the
  987.      original file now refer to the backup file.  The new file is owned
  988.      by the user doing the editing, and its group is the default for
  989.      new files written by the user in that directory.
  990.  
  991.    * Emacs can copy the original file into a backup file, and then
  992.      overwrite the original file with new contents.  After this
  993.      procedure, any other names (i.e., hard links) of the original file
  994.      still refer to the current version of the file.  The file's owner
  995.      and group will be unchanged.
  996.  
  997.    The first method, renaming, is the default.
  998.  
  999.    The variable `backup-by-copying', if non-`nil', says to use the
  1000. second method, which is to copy the original file and overwrite it with
  1001. the new buffer contents.  The variable `file-precious-flag', if
  1002. non-`nil', also has this effect (as a sideline of its main
  1003. significance).  *Note Saving Buffers::.
  1004.  
  1005.    The following two variables, when non-`nil', cause the second method
  1006. to be used in certain special cases.  They have no effect on the
  1007. treatment of files that don't fall into the special cases.
  1008.  
  1009.  - Variable: backup-by-copying
  1010.      This variable controls whether to make backup files by copying.
  1011.      If it is non-`nil', then Emacs always copies the current contents
  1012.      of the file into the backup file before writing the buffer to be
  1013.      saved to the file.  (In many circumstances, this has the same
  1014.      effect as `file-precious-flag'.)
  1015.  
  1016.  - Variable: backup-by-copying-when-linked
  1017.      This variable controls whether to make backups by copying for files
  1018.      with multiple names (hard links).  If it is non-`nil', then Emacs
  1019.      uses copying to create backups for those files.
  1020.  
  1021.      This variable is significant only if `backup-by-copying' is `nil',
  1022.      since copying is always used when that variable is non-`nil'.
  1023.  
  1024.  - Variable: backup-by-copying-when-mismatch
  1025.      This variable controls whether to make backups by copying in cases
  1026.      where renaming would change either the owner or the group of the
  1027.      file.  If it is non-`nil' then Emacs creates backups by copying in
  1028.      such cases.
  1029.  
  1030.      The value has no effect when renaming would not alter the owner or
  1031.      group of the file; that is, for files which are owned by the user
  1032.      and whose group matches the default for a new file created there
  1033.      by the user.
  1034.  
  1035.      This variable is significant only if `backup-by-copying' is `nil',
  1036.      since copying is always used when that variable is non-`nil'.
  1037.  
  1038. 
  1039. File: elisp,  Node: Numbered Backups,  Next: Backup Names,  Prev: Rename or Copy,  Up: Backup Files
  1040.  
  1041. Making and Deleting Numbered Backup Files
  1042. -----------------------------------------
  1043.  
  1044.    If a file's name is `foo', the names of its numbered backup versions
  1045. are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~',
  1046. `foo.~3~', ..., `foo.~259~', and so on.
  1047.  
  1048.  - User Option: version-control
  1049.      This variable controls whether to make a single non-numbered backup
  1050.      file or multiple numbered backups.
  1051.  
  1052.     `nil'
  1053.           Make numbered backups if the visited file already has
  1054.           numbered backups; otherwise, do not.
  1055.  
  1056.     `never'
  1057.           Do not make numbered backups.
  1058.  
  1059.     ANYTHING ELSE
  1060.           Do make numbered backups.
  1061.  
  1062.    The use of numbered backups ultimately leads to a large number of
  1063. backup versions, which must then be deleted.  Emacs can do this
  1064. automatically.
  1065.  
  1066.  - User Option: kept-new-versions
  1067.      The value of this variable is the number of oldest versions to keep
  1068.      when a new numbered backup is made.  The newly made backup is
  1069.      included in the count.  The default value is 2.
  1070.  
  1071.  - User Option: kept-old-versions
  1072.      The value of this variable is the number of oldest versions to keep
  1073.      when a new numbered backup is made.  The default value is 2.
  1074.  
  1075.  - User Option: dired-kept-versions
  1076.      This variable plays a role in Dired's `dired-clean-directory'
  1077.      (`.') command like that played by `kept-old-versions' when a
  1078.      backup file is made.  The default value is 2.
  1079.  
  1080.    If there are backups numbered 1, 2, 3, 5, and 7, and both of these
  1081. variables have the value 2, then the backups numbered 1 and 2 are kept
  1082. as old versions and those numbered 5 and 7 are kept as new versions;
  1083. backup version 3 is deleted.  The function `find-backup-file-name'
  1084. (*note Backup Names::.) is responsible for determining which backup
  1085. versions to delete, but does not delete them itself.
  1086.  
  1087.  - User Option: trim-versions-without-asking
  1088.      If this variable is non-`nil', then saving a file deletes excess
  1089.      backup versions silently.  Otherwise, it asks the user whether to
  1090.      delete them.
  1091.  
  1092. 
  1093. File: elisp,  Node: Backup Names,  Prev: Numbered Backups,  Up: Backup Files
  1094.  
  1095. Naming Backup Files
  1096. -------------------
  1097.  
  1098.    The functions in this section are documented mainly because you can
  1099. customize the naming conventions for backup files by redefining them.
  1100. If you change one, you probably need to change the rest.
  1101.  
  1102.  - Function: backup-file-name-p FILENAME
  1103.      This function returns a non-`nil' value if FILENAME is a possible
  1104.      name for a backup file.  A file with the name FILENAME need not
  1105.      exist; the function just checks the name.
  1106.  
  1107.           (backup-file-name-p "foo")
  1108.                => nil
  1109.           (backup-file-name-p "foo~")
  1110.                => 3
  1111.  
  1112.      The standard definition of this function is as follows:
  1113.  
  1114.           (defun backup-file-name-p (file)
  1115.             "Return non-nil if FILE is a backup file \
  1116.           name (numeric or not)..."
  1117.             (string-match "~$" file))
  1118.  
  1119.      Thus, the function returns a non-`nil' value if the file name ends
  1120.      with a `~'.  (We use a backslash to split the documentation
  1121.      string's first line into two lines in the text, but produce just
  1122.      one line in the string itself.)
  1123.  
  1124.      This simple expression is placed in a separate function to make it
  1125.      easy to redefine for customization.
  1126.  
  1127.  - Function: make-backup-file-name FILENAME
  1128.      This function returns a string which is the name to use for a
  1129.      non-numbered backup file for file FILENAME.  On Unix, this is just
  1130.      FILENAME with a tilde appended.
  1131.  
  1132.      The standard definition of this function is as follows:
  1133.  
  1134.           (defun make-backup-file-name (file)
  1135.             "Create the non-numeric backup file name for FILE..."
  1136.             (concat file "~"))
  1137.  
  1138.      You can change the backup file naming convention by redefining this
  1139.      function.  In the following example, `make-backup-file-name' is
  1140.      redefined to prepend a `.' as well as to append a tilde.
  1141.  
  1142.           (defun make-backup-file-name (filename)
  1143.             (concat "." filename "~"))
  1144.           
  1145.           (make-backup-file-name "backups.texi")
  1146.                => ".backups.texi~"
  1147.  
  1148.  - Function: find-backup-file-name FILENAME
  1149.      This function computes the file name for a new backup file for
  1150.      FILENAME.  It may also propose certain existing backup files for
  1151.      deletion.  `find-backup-file-name' returns a list whose CAR is the
  1152.      name for the new backup file and whose CDR is a list of backup
  1153.      files whose deletion is proposed.
  1154.  
  1155.      Two variables, `kept-old-versions' and `kept-new-versions',
  1156.      determine which old backup versions should be kept (by excluding
  1157.      them from the list of backup files ripe for deletion).  *Note
  1158.      Numbered Backups::.
  1159.  
  1160.      In this example, the value says that `~rms/foo.~5~' is the name to
  1161.      use for the new backup file, and `~rms/foo.~3~' is an "excess"
  1162.      version that the caller should consider deleting now.
  1163.  
  1164.           (find-backup-file-name "~rms/foo")
  1165.                => ("~rms/foo.~5~" "~rms/foo.~3~")
  1166.  
  1167.  - Function: file-newest-backup FILENAME
  1168.      This function returns the name of the most recent backup file for
  1169.      FILENAME, or `nil' that file has no backup files.
  1170.  
  1171.      Some file comparison commands use this function in order to compare
  1172.      a file by default with its most recent backup.
  1173.  
  1174.