-\1f
-File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files
-
-Changing File Names and Attributes
-==================================
-
- The functions in this section rename, copy, delete, link, and set the
-modes of files.
-
- In the functions that have an argument NEWNAME, if a file by the
-name of NEWNAME already exists, the actions taken depend on the value
-of the argument OK-IF-ALREADY-EXISTS:
-
- * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is
- `nil'.
-
- * Request confirmation if OK-IF-ALREADY-EXISTS is a number.
-
- * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
- is any other value.
-
- - Command: add-name-to-file oldname newname &optional
- ok-if-already-exists
- This function gives the file named OLDNAME the additional name
- NEWNAME. This means that NEWNAME becomes a new "hard link" to
- OLDNAME.
-
- In the first part of the following example, we list two files,
- `foo' and `foo3'.
-
- % ls -l fo*
- -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
- -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
-
- Then we evaluate the form `(add-name-to-file "~/lewis/foo"
- "~/lewis/foo2")'. Again we list the files. This shows two names,
- `foo' and `foo2'.
-
- (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
- => nil
-
- % ls -l fo*
- -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
- -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
- -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
-
- Finally, we evaluate the following:
-
- (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
-
- and list the files again. Now there are three names for one file:
- `foo', `foo2', and `foo3'. The old contents of `foo3' are lost.
-
- (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
- => nil
-
- % ls -l fo*
- -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
- -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
- -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
-
- This function is meaningless on VMS, where multiple names for one
- file are not allowed.
-
- See also `file-nlinks' in *Note File Attributes::.
-
- - Command: rename-file filename newname &optional ok-if-already-exists
- This command renames the file FILENAME as NEWNAME.
-
- If FILENAME has additional names aside from FILENAME, it continues
- to have those names. In fact, adding the name NEWNAME with
- `add-name-to-file' and then deleting FILENAME has the same effect
- as renaming, aside from momentary intermediate states.
-
- In an interactive call, this function prompts for FILENAME and
- NEWNAME in the minibuffer; also, it requests confirmation if
- NEWNAME already exists.
-
- - Command: copy-file oldname newname &optional ok-if-exists time
- This command copies the file OLDNAME to NEWNAME. An error is
- signaled if OLDNAME does not exist.
-
- If TIME is non-`nil', then this functions gives the new file the
- same last-modified time that the old one has. (This works on only
- some operating systems.)
-
- In an interactive call, this function prompts for FILENAME and
- NEWNAME in the minibuffer; also, it requests confirmation if
- NEWNAME already exists.
-
- - Command: delete-file filename
- This command deletes the file FILENAME, like the shell command `rm
- FILENAME'. If the file has multiple names, it continues to exist
- under the other names.
-
- A suitable kind of `file-error' error is signaled if the file does
- not exist, or is not deletable. (On Unix, a file is deletable if
- its directory is writable.)
-
- See also `delete-directory' in *Note Create/Delete Dirs::.
-
- - Command: make-symbolic-link filename newname &optional ok-if-exists
- This command makes a symbolic link to FILENAME, named NEWNAME.
- This is like the shell command `ln -s FILENAME NEWNAME'.
-
- In an interactive call, this function prompts for FILENAME and
- NEWNAME in the minibuffer; also, it requests confirmation if
- NEWNAME already exists.
-
- - Function: define-logical-name varname string
- This function defines the logical name NAME to have the value
- STRING. It is available only on VMS.
-
- - Function: set-file-modes filename mode
- This function sets mode bits of FILENAME to MODE (which must be an
- integer). Only the low 12 bits of MODE are used.
-
- - Function: set-default-file-modes mode
- This function sets the default file protection for new files
- created by XEmacs and its subprocesses. Every file created with
- XEmacs initially has this protection. On Unix, the default
- protection is the bitwise complement of the "umask" value.
-
- The argument MODE must be an integer. Only the low 9 bits of MODE
- are used.
-
- Saving a modified version of an existing file does not count as
- creating the file; it does not change the file's mode, and does
- not use the default file protection.
-
- - Function: default-file-modes
- This function returns the current default protection value.
-
- On MS-DOS, there is no such thing as an "executable" file mode bit.
-So Emacs considers a file executable if its name ends in `.com', `.bat'
-or `.exe'. This is reflected in the values returned by `file-modes'
-and `file-attributes'.
-
-\1f
-File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files
-
-File Names
-==========
-
- Files are generally referred to by their names, in XEmacs as
-elsewhere. File names in XEmacs are represented as strings. The
-functions that operate on a file all expect a file name argument.
-
- In addition to operating on files themselves, XEmacs Lisp programs
-often need to operate on the names; i.e., to take them apart and to use
-part of a name to construct related file names. This section describes
-how to manipulate file names.
-
- The functions in this section do not actually access files, so they
-can operate on file names that do not refer to an existing file or
-directory.
-
- On VMS, all these functions understand both VMS file-name syntax and
-Unix syntax. This is so that all the standard Lisp libraries can
-specify file names in Unix syntax and work properly on VMS without
-change. On MS-DOS, these functions understand MS-DOS file-name syntax
-as well as Unix syntax.
-
-* Menu:
-
-* File Name Components:: The directory part of a file name, and the rest.
-* Directory Names:: A directory's name as a directory
- is different from its name as a file.
-* Relative File Names:: Some file names are relative to a current directory.
-* File Name Expansion:: Converting relative file names to absolute ones.
-* Unique File Names:: Generating names for temporary files.
-* File Name Completion:: Finding the completions for a given file name.
-* User Name Completion:: Finding the completions for a given user name.
-
-\1f
-File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names
-
-File Name Components
---------------------
-
- The operating system groups files into directories. To specify a
-file, you must specify the directory and the file's name within that
-directory. Therefore, XEmacs considers a file name as having two main
-parts: the "directory name" part, and the "nondirectory" part (or "file
-name within the directory"). Either part may be empty. Concatenating
-these two parts reproduces the original file name.
-
- On Unix, the directory part is everything up to and including the
-last slash; the nondirectory part is the rest. The rules in VMS syntax
-are complicated.
-
- For some purposes, the nondirectory part is further subdivided into
-the name proper and the "version number". On Unix, only backup files
-have version numbers in their names; on VMS, every file has a version
-number, but most of the time the file name actually used in XEmacs
-omits the version number. Version numbers are found mostly in
-directory lists.
-
- - Function: file-name-directory filename
- This function returns the directory part of FILENAME (or `nil' if
- FILENAME does not include a directory part). On Unix, the
- function returns a string ending in a slash. On VMS, it returns a
- string ending in one of the three characters `:', `]', or `>'.
-
- (file-name-directory "lewis/foo") ; Unix example
- => "lewis/"
- (file-name-directory "foo") ; Unix example
- => nil
- (file-name-directory "[X]FOO.TMP") ; VMS example
- => "[X]"
-
- - Function: file-name-nondirectory filename
- This function returns the nondirectory part of FILENAME.
-
- (file-name-nondirectory "lewis/foo")
- => "foo"
- (file-name-nondirectory "foo")
- => "foo"
- ;; The following example is accurate only on VMS.
- (file-name-nondirectory "[X]FOO.TMP")
- => "FOO.TMP"
-
- - Function: file-name-sans-versions filename &optional
- keep-backup-version
- This function returns FILENAME without any file version numbers,
- backup version numbers, or trailing tildes.
-
- If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup
- version numbers, only true file version numbers.
-
- (file-name-sans-versions "~rms/foo.~1~")
- => "~rms/foo"
- (file-name-sans-versions "~rms/foo~")
- => "~rms/foo"
- (file-name-sans-versions "~rms/foo")
- => "~rms/foo"
- ;; The following example applies to VMS only.
- (file-name-sans-versions "foo;23")
- => "foo"
-
- - Function: file-name-sans-extension filename
- This function returns FILENAME minus its "extension," if any. The
- extension, in a file name, is the part that starts with the last
- `.' in the last name component. For example,
-
- (file-name-sans-extension "foo.lose.c")
- => "foo.lose"
- (file-name-sans-extension "big.hack/foo")
- => "big.hack/foo"
-
-\1f
-File: lispref.info, Node: Directory Names, Next: Relative File Names, Prev: File Name Components, Up: File Names
-
-Directory Names
----------------
-
- A "directory name" is the name of a directory. A directory is a
-kind of file, and it has a file name, which is related to the directory
-name but not identical to it. (This is not quite the same as the usual
-Unix terminology.) These two different names for the same entity are
-related by a syntactic transformation. On Unix, this is simple: a
-directory name ends in a slash, whereas the directory's name as a file
-lacks that slash. On VMS, the relationship is more complicated.
-
- The difference between a directory name and its name as a file is
-subtle but crucial. When an XEmacs variable or function argument is
-described as being a directory name, a file name of a directory is not
-acceptable.
-
- The following two functions convert between directory names and file
-names. They do nothing special with environment variable substitutions
-such as `$HOME', and the constructs `~', and `..'.
-
- - Function: file-name-as-directory filename
- This function returns a string representing FILENAME in a form
- that the operating system will interpret as the name of a
- directory. In Unix, this means appending a slash to the string.
- On VMS, the function converts a string of the form `[X]Y.DIR.1' to
- the form `[X.Y]'.
-
- (file-name-as-directory "~rms/lewis")
- => "~rms/lewis/"
-
- - Function: directory-file-name dirname
- This function returns a string representing DIRNAME in a form that
- the operating system will interpret as the name of a file. On
- Unix, this means removing a final slash from the string. On VMS,
- the function converts a string of the form `[X.Y]' to `[X]Y.DIR.1'.
-
- (directory-file-name "~lewis/")
- => "~lewis"
-
- Directory name abbreviations are useful for directories that are
-normally accessed through symbolic links. Sometimes the users recognize
-primarily the link's name as "the name" of the directory, and find it
-annoying to see the directory's "real" name. If you define the link
-name as an abbreviation for the "real" name, XEmacs shows users the
-abbreviation instead.
-
- If you wish to convert a directory name to its abbreviation, use this
-function:
-
- - Function: abbreviate-file-name dirname &optional hack-homedir
- This function applies abbreviations from `directory-abbrev-alist'
- to its argument, and substitutes `~' for the user's home directory.
-
- If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for
- the user's home directory.
-
-
- - Variable: directory-abbrev-alist
- The variable `directory-abbrev-alist' contains an alist of
- abbreviations to use for file directories. Each element has the
- form `(FROM . TO)', and says to replace FROM with TO when it
- appears in a directory name. The FROM string is actually a
- regular expression; it should always start with `^'. The function
- `abbreviate-file-name' performs these substitutions.
-
- You can set this variable in `site-init.el' to describe the
- abbreviations appropriate for your site.
-
- Here's an example, from a system on which file system `/home/fsf'
- and so on are normally accessed through symbolic links named `/fsf'
- and so on.
-
- (("^/home/fsf" . "/fsf")
- ("^/home/gp" . "/gp")
- ("^/home/gd" . "/gd"))
-
-\1f
-File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names
-
-Absolute and Relative File Names
---------------------------------
-
- All the directories in the file system form a tree starting at the
-root directory. A file name can specify all the directory names
-starting from the root of the tree; then it is called an "absolute"
-file name. Or it can specify the position of the file in the tree
-relative to a default directory; then it is called a "relative" file
-name. On Unix, an absolute file name starts with a slash or a tilde
-(`~'), and a relative one does not. The rules on VMS are complicated.
-
- - Function: file-name-absolute-p filename
- This function returns `t' if file FILENAME is an absolute file
- name, `nil' otherwise. On VMS, this function understands both
- Unix syntax and VMS syntax.
-
- (file-name-absolute-p "~rms/foo")
- => t
- (file-name-absolute-p "rms/foo")
- => nil
- (file-name-absolute-p "/user/rms/foo")
- => t
-
-\1f
-File: lispref.info, Node: File Name Expansion, Next: Unique File Names, Prev: Relative File Names, Up: File Names
-
-Functions that Expand Filenames
--------------------------------
-
- "Expansion" of a file name means converting a relative file name to
-an absolute one. Since this is done relative to a default directory,
-you must specify the default directory name as well as the file name to
-be expanded. Expansion also simplifies file names by eliminating
-redundancies such as `./' and `NAME/../'.
-
- - Function: expand-file-name filename &optional directory
- This function converts FILENAME to an absolute file name. If
- DIRECTORY is supplied, it is the directory to start with if
- FILENAME is relative. (The value of DIRECTORY should itself be an
- absolute directory name; it may start with `~'.) Otherwise, the
- current buffer's value of `default-directory' is used. For
- example:
-
- (expand-file-name "foo")
- => "/xcssun/users/rms/lewis/foo"
- (expand-file-name "../foo")
- => "/xcssun/users/rms/foo"
- (expand-file-name "foo" "/usr/spool/")
- => "/usr/spool/foo"
- (expand-file-name "$HOME/foo")
- => "/xcssun/users/rms/lewis/$HOME/foo"
-
- Filenames containing `.' or `..' are simplified to their canonical
- form:
-
- (expand-file-name "bar/../foo")
- => "/xcssun/users/rms/lewis/foo"
-
- `~/' at the beginning is expanded into the user's home directory.
- A `/' or `~' following a `/'.
-
- Note that `expand-file-name' does _not_ expand environment
- variables; only `substitute-in-file-name' does that.
-
- - Function: file-relative-name filename &optional directory
- This function does the inverse of expansion--it tries to return a
- relative name that is equivalent to FILENAME when interpreted
- relative to DIRECTORY.
-
- If DIRECTORY is `nil' or omitted, the value of `default-directory'
- is used.
-
- (file-relative-name "/foo/bar" "/foo/")
- => "bar")
- (file-relative-name "/foo/bar" "/hack/")
- => "../foo/bar")
-
- - Variable: default-directory
- The value of this buffer-local variable is the default directory
- for the current buffer. It should be an absolute directory name;
- it may start with `~'. This variable is local in every buffer.
-
- `expand-file-name' uses the default directory when its second
- argument is `nil'.
-
- On Unix systems, the value is always a string ending with a slash.
-
- default-directory
- => "/user/lewis/manual/"
-
- - Function: substitute-in-file-name filename
- This function replaces environment variable references in FILENAME
- with the environment variable values. Following standard Unix
- shell syntax, `$' is the prefix to substitute an environment
- variable value.
-
- The environment variable name is the series of alphanumeric
- characters (including underscores) that follow the `$'. If the
- character following the `$' is a `{', then the variable name is
- everything up to the matching `}'.
-
- Here we assume that the environment variable `HOME', which holds
- the user's home directory name, has value `/xcssun/users/rms'.
-
- (substitute-in-file-name "$HOME/foo")
- => "/xcssun/users/rms/foo"
-
- After substitution, a `/' or `~' following a `/' is taken to be
- the start of an absolute file name that overrides what precedes
- it, so everything before that `/' or `~' is deleted. For example:
-
- (substitute-in-file-name "bar/~/foo")
- => "~/foo"
- (substitute-in-file-name "/usr/local/$HOME/foo")
- => "/xcssun/users/rms/foo"
-
- On VMS, `$' substitution is not done, so this function does nothing
- on VMS except discard superfluous initial components as shown
- above.
-
-\1f
-File: lispref.info, Node: Unique File Names, Next: File Name Completion, Prev: File Name Expansion, Up: File Names
-
-Generating Unique File Names
-----------------------------
-
- Some programs need to write temporary files. Here is the usual way
-to construct a name for such a file:
-
- (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory)))
-
-Here we use `(temp-directory)' to specify a directory for temporary
-files--under Unix, it will normally evaluate to `"/tmp/"'. The job of
-`make-temp-name' is to prevent two different users or two different
-processes from trying to use the same name.
-
- - Function: temp-directory
- This function returns the name of the directory to use for
- temporary files. Under Unix, this will be the value of `TMPDIR',
- defaulting to `/tmp'. On Windows, this will be obtained from the
- `TEMP' or `TMP' environment variables, defaulting to `/'.
-
- Note that the `temp-directory' function does not exist under FSF
- Emacs.
-
- - Function: make-temp-name prefix
- This function generates a temporary file name starting with
- PREFIX. The Emacs process number forms part of the result, so
- there is no danger of generating a name being used by another
- process.
-
- (make-temp-name "/tmp/foo")
- => "/tmp/fooGaAQjC"
-
- In addition, this function makes an attempt to choose a name that
- does not specify an existing file. To make this work, PREFIX
- should be an absolute file name.
-
- To avoid confusion, each Lisp application should preferably use a
- unique PREFIX to `make-temp-name'.
-
-\1f
-File: lispref.info, Node: File Name Completion, Next: User Name Completion, Prev: Unique File Names, Up: File Names
-
-File Name Completion
---------------------
-
- This section describes low-level subroutines for completing a file
-name. For other completion functions, see *Note Completion::.
-
- - Function: file-name-all-completions partial-filename directory
- This function returns a list of all possible completions for a file
- whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
- The order of the completions is the order of the files in the
- directory, which is unpredictable and conveys no useful
- information.
-
- The argument PARTIAL-FILENAME must be a file name containing no
- directory part and no slash. The current buffer's default
- directory is prepended to DIRECTORY, if DIRECTORY is not absolute.
-
- In the following example, suppose that the current default
- directory, `~rms/lewis', has five files whose names begin with `f':
- `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
-
- (file-name-all-completions "f" "")
- => ("foo" "file~" "file.c.~2~"
- "file.c.~1~" "file.c")
-
- (file-name-all-completions "fo" "")
- => ("foo")
-
- - Function: file-name-completion filename directory
- This function completes the file name FILENAME in directory
- DIRECTORY. It returns the longest prefix common to all file names
- in directory DIRECTORY that start with FILENAME.
-
- If only one match exists and FILENAME matches it exactly, the
- function returns `t'. The function returns `nil' if directory
- DIRECTORY contains no name starting with FILENAME.
-
- In the following example, suppose that the current default
- directory has five files whose names begin with `f': `foo',
- `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
-
- (file-name-completion "fi" "")
- => "file"
-
- (file-name-completion "file.c.~1" "")
- => "file.c.~1~"
-
- (file-name-completion "file.c.~1~" "")
- => t
-
- (file-name-completion "file.c.~3" "")
- => nil
-
- - User Option: completion-ignored-extensions
- `file-name-completion' usually ignores file names that end in any
- string in this list. It does not ignore them when all the possible
- completions end in one of these suffixes or when a buffer showing
- all possible completions is displayed.
-
- A typical value might look like this:
-
- completion-ignored-extensions
- => (".o" ".elc" "~" ".dvi")
-
-\1f
-File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names
-
-User Name Completion
---------------------
-
- This section describes low-level subroutines for completing a user
-name. For other completion functions, see *Note Completion::.
-
- - Function: user-name-all-completions partial-username
- This function returns a list of all possible completions for a user
- whose name starts with PARTIAL-USERNAME. The order of the
- completions is unpredictable and conveys no useful information.
-
- The argument PARTIAL-USERNAME must be a partial user name
- containing no tilde character and no slash.
-
- - Function: user-name-completion username
- This function completes the user name USERNAME. It returns the
- longest prefix common to all user names that start with USERNAME.
-
- If only one match exists and USERNAME matches it exactly, the
- function returns `t'. The function returns `nil' if no user name
- starting with USERNAME exists.
-
- - Function: user-name-completion-1 username
- This function completes the user name USERNAME, like
- `user-name-completion', differing only in the return value. This
- function returns the cons of the completion returned by
- `user-name-completion', and a boolean indicating whether that
- completion was unique.
-
-\1f
-File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files
-
-Contents of Directories
-=======================
-
- A directory is a kind of file that contains other files entered under
-various names. Directories are a feature of the file system.
-
- XEmacs can list the names of the files in a directory as a Lisp list,
-or display the names in a buffer using the `ls' shell command. In the
-latter case, it can optionally display information about each file,
-depending on the value of switches passed to the `ls' command.
-
- - Function: directory-files directory &optional full-name match-regexp
- nosort files-only
- This function returns a list of the names of the files in the
- directory DIRECTORY. By default, the list is in alphabetical
- order.
-
- If FULL-NAME is non-`nil', the function returns the files'
- absolute file names. Otherwise, it returns just the names
- relative to the specified directory.
-
- If MATCH-REGEXP is non-`nil', this function returns only those
- file names that contain that regular expression--the other file
- names are discarded from the list.
-
- If NOSORT is non-`nil', `directory-files' does not sort the list,
- so you get the file names in no particular order. Use this if you
- want the utmost possible speed and don't care what order the files
- are processed in. If the order of processing is visible to the
- user, then the user will probably be happier if you do sort the
- names.
-
- If FILES-ONLY is the symbol `t', then only the "files" in the
- directory will be returned; subdirectories will be excluded. If
- FILES-ONLY is not `nil' and not `t', then only the subdirectories
- will be returned. Otherwise, if FILES-ONLY is `nil' (the default)
- then both files and subdirectories will be returned.
-
- (directory-files "~lewis")
- => ("#foo#" "#foo.el#" "." ".."
- "dired-mods.el" "files.texi"
- "files.texi.~1~")
-
- An error is signaled if DIRECTORY is not the name of a directory
- that can be read.
-
- - Function: insert-directory file switches &optional wildcard
- full-directory-p
- This function inserts (in the current buffer) a directory listing
- for directory FILE, formatted with `ls' according to SWITCHES. It
- leaves point after the inserted text.
-
- The argument FILE may be either a directory name or a file
- specification including wildcard characters. If WILDCARD is
- non-`nil', that means treat FILE as a file specification with
- wildcards.
-
- If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
- and switches do not contain `-d', so that the listing should show
- the full contents of the directory. (The `-d' option to `ls' says
- to describe a directory itself rather than its contents.)
-
- This function works by running a directory listing program whose
- name is in the variable `insert-directory-program'. If WILDCARD is
- non-`nil', it also runs the shell specified by `shell-file-name',
- to expand the wildcards.
-
- - Variable: insert-directory-program
- This variable's value is the program to run to generate a
- directory listing for the function `insert-directory'.
-
-\1f
-File: lispref.info, Node: Create/Delete Dirs, Next: Magic File Names, Prev: Contents of Directories, Up: Files
-
-Creating and Deleting Directories
-=================================
-
- Most XEmacs Lisp file-manipulation functions get errors when used on
-files that are directories. For example, you cannot delete a directory
-with `delete-file'. These special functions exist to create and delete
-directories.
-
- - Command: make-directory dirname &optional parents
- This function creates a directory named DIRNAME. Interactively,
- the default choice of directory to create is the current default
- directory for file names. That is useful when you have visited a
- file in a nonexistent directory.
-
- Non-interactively, optional argument PARENTS says whether to
- create parent directories if they don't exist. (Interactively, this
- always happens.)
-
- - Command: delete-directory dirname
- This function deletes the directory named DIRNAME. The function
- `delete-file' does not work for files that are directories; you
- must use `delete-directory' in that case.
-
projects / chise / xemacs-chise.git / blobdiff