@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/files
@node Files, Backups and Auto-Saving, Documentation, Top
See also @code{delete-directory} in @ref{Create/Delete Dirs}.
@end deffn
-@defun define-logical-name varname string
-This function defines the logical name @var{varname} to have the value
-@var{string}. It is available only on VMS.
-@end defun
-
-@defun set-file-modes filename mode
+@deffn Command set-file-modes filename mode
This function sets mode bits of @var{filename} to @var{mode} (which
-must be an integer). Only the low 12 bits of @var{mode} are used.
+must be an integer when the function is called non-interactively).
+Only the low 12 bits of @var{mode} are used.
+
+Interactively, @var{mode} is read from the minibuffer using
+@code{read-file-modes}, which accepts mode bits either as a number or
+as a character string representing the mode bits symbolically. See
+the description of @code{read-file-modes} below for the supported
+forms of symbolic notation for mode bits.
+
This function recursively follows symbolic links at all levels for
@var{filename}.
-@end defun
+@end deffn
@c Emacs 19 feature
@defun set-default-file-modes mode
This function returns the current default protection value.
@end defun
+@defun read-file-modes &optional prompt base-file
+This function reads file mode bits from the minibuffer. The optional
+argument @var{prompt} specifies a non-default prompt. Second optional
+argument @var{base-file} is the name of a file on whose permissions to
+base the mode bits that this function returns, if what the user types
+specifies mode bits relative to permissions of an existing file.
+
+If user input represents an octal number, this function returns that
+number. If it is a complete symbolic specification of mode bits, as
+in @code{"u=rwx"}, the function converts it to the equivalent numeric
+value using @code{file-modes-symbolic-to-number} and returns the
+result. If the specification is relative, as in @code{"o+g"}, then
+the permissions on which the specification is based are taken from the
+mode bits of @var{base-file}. If @var{base-file} is omitted or
+@code{nil}, the function uses @code{0} as the base mode bits. The
+complete and relative specifications can be combined, as in
+@code{"u+r,g+rx,o+r,g-w"}. @xref{File Permissions,,, coreutils, The
+@sc{gnu} @code{Coreutils} Manual}, for detailed description of
+symbolic mode bits specifications.
+@end defun
+
+@defun file-modes-symbolic-to-number modes &optional base-modes
+This subroutine converts a symbolic specification of file mode bits in
+@var{modes} into the equivalent numeric value. If the symbolic
+specification is based on an existing file, that file's mode bits are
+taken from the optional argument @var{base-modes}; if that argument is
+omitted or @code{nil}, it defaults to zero, i.e.@: no access rights at
+all.
+@end defun
+
@defun set-file-times filename &optional time
This function sets the access and modification times of @var{filename}
to @var{time}. The return value is @code{t} if the times are successfully
On MS-DOS and MS-Windows, these functions (like the function that
actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
where backslashes separate the components, as well as Unix syntax; but
-they always return Unix syntax. On VMS, these functions (and the ones
-that operate on files) understand both VMS file-name syntax and Unix
-syntax. This enables Lisp programs to specify file names in Unix syntax
-and work properly on all systems without change.
+they always return Unix syntax. This enables Lisp programs to specify
+file names in Unix syntax and work properly on all systems without
+change.
@menu
* File Name Components:: The directory part of a file name, and the rest.
On most systems, the directory part is everything up to and including
the last slash (backslash is also allowed in input on MS-DOS or
-MS-Windows); the nondirectory part is the rest. The rules in VMS syntax
-are complicated.
+MS-Windows); the nondirectory part is the rest.
For some purposes, the nondirectory part is further subdivided into
the name proper and the @dfn{version number}. On most systems, 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 Emacs omits the version number, so that version numbers in Emacs are
-found mostly in directory lists.
+backup files have version numbers in their names.
@defun file-name-directory filename
This function returns the directory part of @var{filename}, as a
@var{filename} does not include a directory part.
On GNU and Unix systems, a string returned by this function always
-ends in a slash. On MS-DOS it can also end in a colon. On VMS, it
-returns a string ending in one of the three characters @samp{:},
-@samp{]}, or @samp{>}.
+ends in a slash. On MS-DOS it can also end in a colon.
@example
@group
(file-name-directory "foo") ; @r{Unix example}
@result{} nil
@end group
-@group
-(file-name-directory "[X]FOO.TMP") ; @r{VMS example}
- @result{} "[X]"
-@end group
@end example
@end defun
(file-name-nondirectory "lewis/")
@result{} ""
@end group
-@group
-;; @r{The following example is accurate only on VMS.}
-(file-name-nondirectory "[X]FOO.TMP")
- @result{} "FOO.TMP"
-@end group
@end example
@end defun
(file-name-sans-versions "~rms/foo")
@result{} "~rms/foo"
@end group
-@group
-;; @r{The following example applies to VMS only.}
-(file-name-sans-versions "foo;23")
- @result{} "foo"
-@end group
@end example
@end defun
This function returns @var{filename}'s final ``extension,'' if any,
after applying @code{file-name-sans-versions} to remove any
version/backup part. The extension, in a file name, is the part that
-starts with the last @samp{.} in the last name component (minus
-any version/backup part).
+follows the last @samp{.} in the last name component (minus any
+version/backup part).
This function returns @code{nil} for extensionless file names such as
@file{foo}. It returns @code{""} for null extensions, as in
or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
MS-Windows, an absolute file name starts with a slash or a backslash, or
with a drive specification @samp{@var{x}:/}, where @var{x} is the
-@dfn{drive letter}. The rules on VMS are complicated.
+@dfn{drive letter}.
@defun file-name-absolute-p filename
This function returns @code{t} if file @var{filename} is an absolute
-file name, @code{nil} otherwise. On VMS, this function understands both
-Unix syntax and VMS syntax.
+file name, @code{nil} otherwise.
@example
@group
same as the usual Unix terminology.) These two different names for
the same entity are related by a syntactic transformation. On GNU and
Unix systems, this is simple: a directory name ends in a slash,
-whereas the directory's name as a file lacks that slash. On MS-DOS and
-VMS, the relationship is more complicated.
+whereas the directory's name as a file lacks that slash. On MS-DOS
+the relationship is more complicated.
The difference between a directory name and its name as a file is
subtle but crucial. When an Emacs variable or function argument is
This function returns a string representing @var{filename} in a form
that the operating system will interpret as the name of a directory. On
most systems, this means appending a slash to the string (if it does not
-already end in one). On VMS, the function converts a string of the form
-@file{[X]Y.DIR.1} to the form @file{[X.Y]}.
+already end in one).
@example
@group
This function returns a string representing @var{dirname} in a form that
the operating system will interpret as the name of a file. On most
systems, this means removing the final slash (or backslash) from the
-string. On VMS, the function converts a string of the form @file{[X.Y]}
-to @file{[X]Y.DIR.1}.
+string.
@example
@group
@code{expand-file-name} uses the default directory when its second
argument is @code{nil}.
-Aside from VMS, the value is always a string ending with a slash.
+The value is always a string ending with a slash.
@example
@group
@end group
@end example
-On VMS, @samp{$} substitution is not done, so this function does nothing
-on VMS except discard superfluous initial components as shown above.
@end defun
@node Unique File Names
of file-attributes}).
@end defun
-@defun file-name-all-versions file dirname
-This function returns a list of all versions of the file named
-@var{file} in directory @var{dirname}. It is only available on VMS.
-@end defun
-
@defun file-expand-wildcards pattern &optional full
This function expands the wildcard pattern @var{pattern}, returning
a list of file names that match it.
@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
@code{file-truename}, @code{file-writable-p},
@code{find-backup-file-name},
-@code{find-file-noselect},@*
+@c Not sure why it was here: @code{find-file-noselect},@*
@code{get-file-buffer},
@code{insert-directory},
@code{insert-file-contents},@*
@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
@code{file-truename}, @code{file-writable-p},
@code{find-backup-file-name},
-@code{find-file-noselect},
+@c Not sure why it was here: @code{find-file-noselect},
@code{get-file-buffer},
@code{insert-directory},
@code{insert-file-contents},
This function returns the name of a directory that is not magic. It
uses the directory part of @var{filename} if that is not magic. For a
magic file name, it invokes the file name handler, which therefore
-decides what value to return.
+decides what value to return. If @var{filename} is not accessible
+from a local process, then the file name handler should indicate it by
+returning @code{nil}.
This is useful for running a subprocess; every subprocess must have a
non-magic directory to serve as its current directory, and this function
Each format definition is a list of this form:
@example
-(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
+(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn} @var{preserve})
@end example
@end defvar
A minor-mode function to call after visiting a file converted from this
format. The function is called with one argument, the integer 1;
that tells a minor-mode function to enable the mode.
+
+@item preserve
+A flag, @code{t} if @code{format-write-file} should not remove this format
+from @code{buffer-file-format}.
@end table
The function @code{insert-file-contents} automatically recognizes file
@deffn Command format-write-file file format &optional confirm
This command writes the current buffer contents into the file
@var{file} in format @var{format}, and makes that format the default
-for future saves of the buffer. The argument @var{format} is a list
-of format names. Except for the @var{format} argument, this command
+for future saves of the buffer. That is, it sets the buffer-local value
+of @code{buffer-file-format} to @var{format}. It then appends any
+elements of the previous value with a non-nil @var{preserve} flag (see
+above), if they are not already present in the new value.
+The argument @var{format} is a list of format names.
+Except for the @var{format} argument, this command
is similar to @code{write-file}. In particular, @var{confirm} has the
same meaning and interactive treatment as the corresponding argument
to @code{write-file}. @xref{Definition of write-file}.