annotate doc/lispref/files.texi @ 106146:cfc4f2fef78c

(calcFunc-vunpack): Let `calc-twos-complement-mode' be nil.
author Jay Belanger <jay.p.belanger@gmail.com>
date Fri, 20 Nov 2009 01:00:27 +0000
parents c8da8bef4903
children 1d1d5d9bd884
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
100974
cb5d2387102c Add 2009 to copyright years.
Glenn Morris <rgm@gnu.org>
parents: 100115
diff changeset
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
84116
0ba80d073e27 (setfilename): Go up one more level to ../../info.
Glenn Morris <rgm@gnu.org>
parents: 84067
diff changeset
6 @setfilename ../../info/files
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
7 @node Files, Backups and Auto-Saving, Documentation, Top
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
8 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
9 @chapter Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
10
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
11 In Emacs, you can find, create, view, save, and otherwise work with
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
12 files and file directories. This chapter describes most of the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
13 file-related functions of Emacs Lisp, but a few others are described in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
14 @ref{Buffers}, and those related to backups and auto-saving are
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
15 described in @ref{Backups and Auto-Saving}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
16
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
17 Many of the file functions take one or more arguments that are file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
18 names. A file name is actually a string. Most of these functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
19 expand file name arguments by calling @code{expand-file-name}, so that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
20 @file{~} is handled correctly, as are relative file names (including
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
21 @samp{../}). These functions don't recognize environment variable
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
22 substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
23
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
24 When file I/O functions signal Lisp errors, they usually use the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
25 condition @code{file-error} (@pxref{Handling Errors}). The error
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
26 message is in most cases obtained from the operating system, according
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
27 to locale @code{system-message-locale}, and decoded using coding system
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
28 @code{locale-coding-system} (@pxref{Locales}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
29
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
30 @menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
31 * Visiting Files:: Reading files into Emacs buffers for editing.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
32 * Saving Buffers:: Writing changed buffers back into files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
33 * Reading from Files:: Reading files into buffers without visiting.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
34 * Writing to Files:: Writing new files from parts of buffers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
35 * File Locks:: Locking and unlocking files, to prevent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
36 simultaneous editing by two people.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
37 * Information about Files:: Testing existence, accessibility, size of files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
38 * Changing Files:: Renaming files, changing protection, etc.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
39 * File Names:: Decomposing and expanding file names.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
40 * Contents of Directories:: Getting a list of the files in a directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
41 * Create/Delete Dirs:: Creating and Deleting Directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
42 * Magic File Names:: Defining "magic" special handling
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
43 for certain file names.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
44 * Format Conversion:: Conversion to and from various file formats.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
45 @end menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
46
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
47 @node Visiting Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
48 @section Visiting Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
49 @cindex finding files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
50 @cindex visiting files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
51
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
52 Visiting a file means reading a file into a buffer. Once this is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
53 done, we say that the buffer is @dfn{visiting} that file, and call the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
54 file ``the visited file'' of the buffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
55
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
56 A file and a buffer are two different things. A file is information
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
57 recorded permanently in the computer (unless you delete it). A buffer,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
58 on the other hand, is information inside of Emacs that will vanish at
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
59 the end of the editing session (or when you kill the buffer). Usually,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
60 a buffer contains information that you have copied from a file; then we
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
61 say the buffer is visiting that file. The copy in the buffer is what
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
62 you modify with editing commands. Such changes to the buffer do not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
63 change the file; therefore, to make the changes permanent, you must
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
64 @dfn{save} the buffer, which means copying the altered buffer contents
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
65 back into the file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
66
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
67 In spite of the distinction between files and buffers, people often
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
68 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
69 ``I am editing a file,'' rather than, ``I am editing a buffer that I
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
70 will soon save as a file of the same name.'' Humans do not usually need
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
71 to make the distinction explicit. When dealing with a computer program,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
72 however, it is good to keep the distinction in mind.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
73
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
74 @menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
75 * Visiting Functions:: The usual interface functions for visiting.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
76 * Subroutines of Visiting:: Lower-level subroutines that they use.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
77 @end menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
78
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
79 @node Visiting Functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
80 @subsection Functions for Visiting Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
81
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
82 This section describes the functions normally used to visit files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
83 For historical reasons, these functions have names starting with
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
84 @samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
85 functions and variables that access the visited file name of a buffer or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
86 that find an existing buffer by its visited file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
87
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
88 In a Lisp program, if you want to look at the contents of a file but
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
89 not alter it, the fastest way is to use @code{insert-file-contents} in a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
90 temporary buffer. Visiting the file is not necessary and takes longer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
91 @xref{Reading from Files}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
92
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
93 @deffn Command find-file filename &optional wildcards
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
94 This command selects a buffer visiting the file @var{filename},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
95 using an existing buffer if there is one, and otherwise creating a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
96 new buffer and reading the file into it. It also returns that buffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
97
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
98 Aside from some technical details, the body of the @code{find-file}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
99 function is basically equivalent to:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
100
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
101 @smallexample
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
102 (switch-to-buffer (find-file-noselect filename nil nil wildcards))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
103 @end smallexample
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
104
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
105 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
106 (See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
107
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
108 If @var{wildcards} is non-@code{nil}, which is always true in an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
109 interactive call, then @code{find-file} expands wildcard characters in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
110 @var{filename} and visits all the matching files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
111
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
112 When @code{find-file} is called interactively, it prompts for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
113 @var{filename} in the minibuffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
114 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
115
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
116 @defun find-file-noselect filename &optional nowarn rawfile wildcards
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
117 This function is the guts of all the file-visiting functions. It
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
118 returns a buffer visiting the file @var{filename}. You may make the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
119 buffer current or display it in a window if you wish, but this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
120 function does not do so.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
121
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
122 The function returns an existing buffer if there is one; otherwise it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
123 creates a new buffer and reads the file into it. When
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
124 @code{find-file-noselect} uses an existing buffer, it first verifies
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
125 that the file has not changed since it was last visited or saved in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
126 that buffer. If the file has changed, this function asks the user
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
127 whether to reread the changed file. If the user says @samp{yes}, any
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
128 edits previously made in the buffer are lost.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
129
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
130 Reading the file involves decoding the file's contents (@pxref{Coding
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
131 Systems}), including end-of-line conversion, and format conversion
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
132 (@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
133 then @code{find-file-noselect} expands wildcard characters in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
134 @var{filename} and visits all the matching files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
135
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
136 This function displays warning or advisory messages in various peculiar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
137 cases, unless the optional argument @var{nowarn} is non-@code{nil}. For
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
138 example, if it needs to create a buffer, and there is no file named
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
139 @var{filename}, it displays the message @samp{(New file)} in the echo
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
140 area, and leaves the buffer empty.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
141
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
142 The @code{find-file-noselect} function normally calls
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
143 @code{after-find-file} after reading the file (@pxref{Subroutines of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
144 Visiting}). That function sets the buffer major mode, parses local
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
145 variables, warns the user if there exists an auto-save file more recent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
146 than the file just visited, and finishes by running the functions in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
147 @code{find-file-hook}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
148
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
149 If the optional argument @var{rawfile} is non-@code{nil}, then
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
150 @code{after-find-file} is not called, and the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
151 @code{find-file-not-found-functions} are not run in case of failure.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
152 What's more, a non-@code{nil} @var{rawfile} value suppresses coding
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
153 system conversion and format conversion.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
154
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
155 The @code{find-file-noselect} function usually returns the buffer that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
156 is visiting the file @var{filename}. But, if wildcards are actually
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
157 used and expanded, it returns a list of buffers that are visiting the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
158 various files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
159
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
160 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
161 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
162 (find-file-noselect "/etc/fstab")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
163 @result{} #<buffer fstab>
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
164 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
165 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
166 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
167
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
168 @deffn Command find-file-other-window filename &optional wildcards
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
169 This command selects a buffer visiting the file @var{filename}, but
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
170 does so in a window other than the selected window. It may use another
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
171 existing window or split a window; see @ref{Displaying Buffers}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
172
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
173 When this command is called interactively, it prompts for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
174 @var{filename}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
175 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
176
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
177 @deffn Command find-file-read-only filename &optional wildcards
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
178 This command selects a buffer visiting the file @var{filename}, like
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
179 @code{find-file}, but it marks the buffer as read-only. @xref{Read Only
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
180 Buffers}, for related functions and variables.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
181
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
182 When this command is called interactively, it prompts for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
183 @var{filename}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
184 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
185
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
186 @deffn Command view-file filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
187 This command visits @var{filename} using View mode, returning to the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
188 previous buffer when you exit View mode. View mode is a minor mode that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
189 provides commands to skim rapidly through the file, but does not let you
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
190 modify the text. Entering View mode runs the normal hook
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
191 @code{view-mode-hook}. @xref{Hooks}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
192
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
193 When @code{view-file} is called interactively, it prompts for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
194 @var{filename}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
195 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
196
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
197 @defopt find-file-wildcards
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
198 If this variable is non-@code{nil}, then the various @code{find-file}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
199 commands check for wildcard characters and visit all the files that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
200 match them (when invoked interactively or when their @var{wildcards}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
201 argument is non-@code{nil}). If this option is @code{nil}, then
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
202 the @code{find-file} commands ignore their @var{wildcards} argument
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
203 and never treat wildcard characters specially.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
204 @end defopt
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
205
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103264
diff changeset
206 @defopt find-file-hook
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
207 The value of this variable is a list of functions to be called after a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
208 file is visited. The file's local-variables specification (if any) will
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
209 have been processed before the hooks are run. The buffer visiting the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
210 file is current when the hook functions are run.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
211
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
212 This variable is a normal hook. @xref{Hooks}.
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103264
diff changeset
213 @end defopt
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
214
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
215 @defvar find-file-not-found-functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
216 The value of this variable is a list of functions to be called when
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
217 @code{find-file} or @code{find-file-noselect} is passed a nonexistent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
218 file name. @code{find-file-noselect} calls these functions as soon as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
219 it detects a nonexistent file. It calls them in the order of the list,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
220 until one of them returns non-@code{nil}. @code{buffer-file-name} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
221 already set up.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
222
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
223 This is not a normal hook because the values of the functions are
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
224 used, and in many cases only some of the functions are called.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
225 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
226
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
227 @node Subroutines of Visiting
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
228 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
229 @subsection Subroutines of Visiting
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
230
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
231 The @code{find-file-noselect} function uses two important subroutines
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
232 which are sometimes useful in user Lisp code: @code{create-file-buffer}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
233 and @code{after-find-file}. This section explains how to use them.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
234
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
235 @defun create-file-buffer filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
236 This function creates a suitably named buffer for visiting
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
237 @var{filename}, and returns it. It uses @var{filename} (sans directory)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
238 as the name if that name is free; otherwise, it appends a string such as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
239 @samp{<2>} to get an unused name. See also @ref{Creating Buffers}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
240
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
241 @strong{Please note:} @code{create-file-buffer} does @emph{not}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
242 associate the new buffer with a file and does not select the buffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
243 It also does not use the default major mode.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
244
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
245 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
246 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
247 (create-file-buffer "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
248 @result{} #<buffer foo>
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
249 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
250 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
251 (create-file-buffer "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
252 @result{} #<buffer foo<2>>
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
253 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
254 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
255 (create-file-buffer "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
256 @result{} #<buffer foo<3>>
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
257 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
258 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
259
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
260 This function is used by @code{find-file-noselect}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
261 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
262 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
263
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
264 @defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
265 This function sets the buffer major mode, and parses local variables
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
266 (@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
267 and by the default revert function (@pxref{Reverting}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
268
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
269 @cindex new file message
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
270 @cindex file open error
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
271 If reading the file got an error because the file does not exist, but
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
272 its directory does exist, the caller should pass a non-@code{nil} value
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
273 for @var{error}. In that case, @code{after-find-file} issues a warning:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
274 @samp{(New file)}. For more serious errors, the caller should usually not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
275 call @code{after-find-file}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
276
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
277 If @var{warn} is non-@code{nil}, then this function issues a warning
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
278 if an auto-save file exists and is more recent than the visited file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
279
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
280 If @var{noauto} is non-@code{nil}, that says not to enable or disable
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
281 Auto-Save mode. The mode remains enabled if it was enabled before.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
282
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
283 If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
284 means this call was from @code{revert-buffer}. This has no direct
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
285 effect, but some mode functions and hook functions check the value
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
286 of this variable.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
287
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
288 If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
289 major mode, don't process local variables specifications in the file,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
290 and don't run @code{find-file-hook}. This feature is used by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
291 @code{revert-buffer} in some cases.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
292
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
293 The last thing @code{after-find-file} does is call all the functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
294 in the list @code{find-file-hook}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
295 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
296
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
297 @node Saving Buffers
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
298 @section Saving Buffers
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
299 @cindex saving buffers
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
300
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
301 When you edit a file in Emacs, you are actually working on a buffer
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
302 that is visiting that file---that is, the contents of the file are
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
303 copied into the buffer and the copy is what you edit. Changes to the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
304 buffer do not change the file until you @dfn{save} the buffer, which
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
305 means copying the contents of the buffer into the file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
306
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
307 @deffn Command save-buffer &optional backup-option
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
308 This function saves the contents of the current buffer in its visited
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
309 file if the buffer has been modified since it was last visited or saved.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
310 Otherwise it does nothing.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
311
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
312 @code{save-buffer} is responsible for making backup files. Normally,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
313 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
314 file only if this is the first save since visiting the file. Other
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
315 values for @var{backup-option} request the making of backup files in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
316 other circumstances:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
317
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
318 @itemize @bullet
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
319 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
320 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
321 @code{save-buffer} function marks this version of the file to be
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
322 backed up when the buffer is next saved.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
323
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
324 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
325 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
326 @code{save-buffer} function unconditionally backs up the previous
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
327 version of the file before saving it.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
328
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
329 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
330 With an argument of 0, unconditionally do @emph{not} make any backup file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
331 @end itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
332 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
333
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
334 @deffn Command save-some-buffers &optional save-silently-p pred
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
335 @anchor{Definition of save-some-buffers}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
336 This command saves some modified file-visiting buffers. Normally it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
337 asks the user about each buffer. But if @var{save-silently-p} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
338 non-@code{nil}, it saves all the file-visiting buffers without querying
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
339 the user.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
340
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
341 The optional @var{pred} argument controls which buffers to ask about
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
342 (or to save silently if @var{save-silently-p} is non-@code{nil}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
343 If it is @code{nil}, that means to ask only about file-visiting buffers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
344 If it is @code{t}, that means also offer to save certain other non-file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
345 buffers---those that have a non-@code{nil} buffer-local value of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
346 @code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
347 @samp{yes} to saving a non-file buffer is asked to specify the file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
348 name to use. The @code{save-buffers-kill-emacs} function passes the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
349 value @code{t} for @var{pred}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
350
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
351 If @var{pred} is neither @code{t} nor @code{nil}, then it should be
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
352 a function of no arguments. It will be called in each buffer to decide
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
353 whether to offer to save that buffer. If it returns a non-@code{nil}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
354 value in a certain buffer, that means do offer to save that buffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
355 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
356
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
357 @deffn Command write-file filename &optional confirm
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
358 @anchor{Definition of write-file}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
359 This function writes the current buffer into file @var{filename}, makes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
360 the buffer visit that file, and marks it not modified. Then it renames
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
361 the buffer based on @var{filename}, appending a string like @samp{<2>}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
362 if necessary to make a unique buffer name. It does most of this work by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
363 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
364 @code{save-buffer}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
365
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
366 If @var{confirm} is non-@code{nil}, that means to ask for confirmation
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
367 before overwriting an existing file. Interactively, confirmation is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
368 required, unless the user supplies a prefix argument.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
369
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
370 If @var{filename} is an existing directory, or a symbolic link to one,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
371 @code{write-file} uses the name of the visited file, in directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
372 @var{filename}. If the buffer is not visiting a file, it uses the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
373 buffer name instead.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
374 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
375
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
376 Saving a buffer runs several hooks. It also performs format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
377 conversion (@pxref{Format Conversion}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
378
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
379 @defvar write-file-functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
380 The value of this variable is a list of functions to be called before
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
381 writing out a buffer to its visited file. If one of them returns
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
382 non-@code{nil}, the file is considered already written and the rest of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
383 the functions are not called, nor is the usual code for writing the file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
384 executed.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
385
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
386 If a function in @code{write-file-functions} returns non-@code{nil}, it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
387 is responsible for making a backup file (if that is appropriate).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
388 To do so, execute the following code:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
389
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
390 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
391 (or buffer-backed-up (backup-buffer))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
392 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
393
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
394 You might wish to save the file modes value returned by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
395 @code{backup-buffer} and use that (if non-@code{nil}) to set the mode
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
396 bits of the file that you write. This is what @code{save-buffer}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
397 normally does. @xref{Making Backups,, Making Backup Files}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
398
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
399 The hook functions in @code{write-file-functions} are also responsible
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
400 for encoding the data (if desired): they must choose a suitable coding
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
401 system and end-of-line conversion (@pxref{Lisp and Coding Systems}),
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
402 perform the encoding (@pxref{Explicit Encoding}), and set
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
403 @code{last-coding-system-used} to the coding system that was used
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
404 (@pxref{Encoding and I/O}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
405
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
406 If you set this hook locally in a buffer, it is assumed to be
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
407 associated with the file or the way the contents of the buffer were
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
408 obtained. Thus the variable is marked as a permanent local, so that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
409 changing the major mode does not alter a buffer-local value. On the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
410 other hand, calling @code{set-visited-file-name} will reset it.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
411 If this is not what you want, you might like to use
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
412 @code{write-contents-functions} instead.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
413
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
414 Even though this is not a normal hook, you can use @code{add-hook} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
415 @code{remove-hook} to manipulate the list. @xref{Hooks}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
416 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
417
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
418 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
419 @defvar write-contents-functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
420 This works just like @code{write-file-functions}, but it is intended
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
421 for hooks that pertain to the buffer's contents, not to the particular
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
422 visited file or its location. Such hooks are usually set up by major
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
423 modes, as buffer-local bindings for this variable. This variable
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
424 automatically becomes buffer-local whenever it is set; switching to a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
425 new major mode always resets this variable, but calling
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
426 @code{set-visited-file-name} does not.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
427
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
428 If any of the functions in this hook returns non-@code{nil}, the file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
429 is considered already written and the rest are not called and neither
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
430 are the functions in @code{write-file-functions}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
431 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
432
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
433 @defopt before-save-hook
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
434 This normal hook runs before a buffer is saved in its visited file,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
435 regardless of whether that is done normally or by one of the hooks
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
436 described above. For instance, the @file{copyright.el} program uses
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
437 this hook to make sure the file you are saving has the current year in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
438 its copyright notice.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
439 @end defopt
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
440
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
441 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
442 @defopt after-save-hook
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
443 This normal hook runs after a buffer has been saved in its visited file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
444 One use of this hook is in Fast Lock mode; it uses this hook to save the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
445 highlighting information in a cache file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
446 @end defopt
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
447
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
448 @defopt file-precious-flag
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
449 If this variable is non-@code{nil}, then @code{save-buffer} protects
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
450 against I/O errors while saving by writing the new file to a temporary
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
451 name instead of the name it is supposed to have, and then renaming it to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
452 the intended name after it is clear there are no errors. This procedure
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
453 prevents problems such as a lack of disk space from resulting in an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
454 invalid file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
455
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
456 As a side effect, backups are necessarily made by copying. @xref{Rename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
457 or Copy}. Yet, at the same time, saving a precious file always breaks
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
458 all hard links between the file you save and other file names.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
459
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
460 Some modes give this variable a non-@code{nil} buffer-local value
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
461 in particular buffers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
462 @end defopt
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
463
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
464 @defopt require-final-newline
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
465 This variable determines whether files may be written out that do
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
466 @emph{not} end with a newline. If the value of the variable is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
467 @code{t}, then @code{save-buffer} silently adds a newline at the end of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
468 the file whenever the buffer being saved does not already end in one.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
469 If the value of the variable is non-@code{nil}, but not @code{t}, then
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
470 @code{save-buffer} asks the user whether to add a newline each time the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
471 case arises.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
472
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
473 If the value of the variable is @code{nil}, then @code{save-buffer}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
474 doesn't add newlines at all. @code{nil} is the default value, but a few
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
475 major modes set it to @code{t} in particular buffers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
476 @end defopt
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
477
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
478 See also the function @code{set-visited-file-name} (@pxref{Buffer File
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
479 Name}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
480
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
481 @node Reading from Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
482 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
483 @section Reading from Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
484 @cindex reading from files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
485
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
486 You can copy a file from the disk and insert it into a buffer
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
487 using the @code{insert-file-contents} function. Don't use the user-level
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
488 command @code{insert-file} in a Lisp program, as that sets the mark.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
489
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
490 @defun insert-file-contents filename &optional visit beg end replace
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
491 This function inserts the contents of file @var{filename} into the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
492 current buffer after point. It returns a list of the absolute file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
493 and the length of the data inserted. An error is signaled if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
494 @var{filename} is not the name of a file that can be read.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
495
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
496 The function @code{insert-file-contents} checks the file contents
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
497 against the defined file formats, and converts the file contents if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
498 appropriate and also calls the functions in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
499 the list @code{after-insert-file-functions}. @xref{Format Conversion}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
500 Normally, one of the functions in the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
501 @code{after-insert-file-functions} list determines the coding system
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
502 (@pxref{Coding Systems}) used for decoding the file's contents,
101050
ceb69a8a308a (Reading from Files): Document that null bytes force no-conversion when visiting
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
503 including end-of-line conversion. However, if the file contains null
ceb69a8a308a (Reading from Files): Document that null bytes force no-conversion when visiting
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
504 bytes, it is by default visited without any code conversions; see
ceb69a8a308a (Reading from Files): Document that null bytes force no-conversion when visiting
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
505 @ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to
ceb69a8a308a (Reading from Files): Document that null bytes force no-conversion when visiting
Eli Zaretskii <eliz@gnu.org>
parents: 100974
diff changeset
506 control this behavior.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
507
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
508 If @var{visit} is non-@code{nil}, this function additionally marks the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
509 buffer as unmodified and sets up various fields in the buffer so that it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
510 is visiting the file @var{filename}: these include the buffer's visited
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
511 file name and its last save file modtime. This feature is used by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
512 @code{find-file-noselect} and you probably should not use it yourself.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
513
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
514 If @var{beg} and @var{end} are non-@code{nil}, they should be integers
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
515 specifying the portion of the file to insert. In this case, @var{visit}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
516 must be @code{nil}. For example,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
517
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
518 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
519 (insert-file-contents filename nil 0 500)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
520 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
521
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
522 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
523 inserts the first 500 characters of a file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
524
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
525 If the argument @var{replace} is non-@code{nil}, it means to replace the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
526 contents of the buffer (actually, just the accessible portion) with the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
527 contents of the file. This is better than simply deleting the buffer
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
528 contents and inserting the whole file, because (1) it preserves some
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
529 marker positions and (2) it puts less data in the undo list.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
530
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
531 It is possible to read a special file (such as a FIFO or an I/O device)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
532 with @code{insert-file-contents}, as long as @var{replace} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
533 @var{visit} are @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
534 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
535
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
536 @defun insert-file-contents-literally filename &optional visit beg end replace
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
537 This function works like @code{insert-file-contents} except that it does
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
538 not do format decoding (@pxref{Format Conversion}), does not do
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
539 character code conversion (@pxref{Coding Systems}), does not run
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
540 @code{find-file-hook}, does not perform automatic uncompression, and so
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
541 on.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
542 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
543
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
544 If you want to pass a file name to another process so that another
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
545 program can read the file, use the function @code{file-local-copy}; see
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
546 @ref{Magic File Names}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
547
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
548 @node Writing to Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
549 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
550 @section Writing to Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
551 @cindex writing to files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
552
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
553 You can write the contents of a buffer, or part of a buffer, directly
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
554 to a file on disk using the @code{append-to-file} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
555 @code{write-region} functions. Don't use these functions to write to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
556 files that are being visited; that could cause confusion in the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
557 mechanisms for visiting.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
558
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
559 @deffn Command append-to-file start end filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
560 This function appends the contents of the region delimited by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
561 @var{start} and @var{end} in the current buffer to the end of file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
562 @var{filename}. If that file does not exist, it is created. This
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
563 function returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
564
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
565 An error is signaled if @var{filename} specifies a nonwritable file,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
566 or a nonexistent file in a directory where files cannot be created.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
567
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
568 When called from Lisp, this function is completely equivalent to:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
569
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
570 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
571 (write-region start end filename t)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
572 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
573 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
574
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
575 @deffn Command write-region start end filename &optional append visit lockname mustbenew
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
576 This function writes the region delimited by @var{start} and @var{end}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
577 in the current buffer into the file specified by @var{filename}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
578
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
579 If @var{start} is @code{nil}, then the command writes the entire buffer
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
580 contents (@emph{not} just the accessible portion) to the file and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
581 ignores @var{end}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
582
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
583 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
584 If @var{start} is a string, then @code{write-region} writes or appends
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
585 that string, rather than text from the buffer. @var{end} is ignored in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
586 this case.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
587
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
588 If @var{append} is non-@code{nil}, then the specified text is appended
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
589 to the existing file contents (if any). If @var{append} is an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
590 integer, @code{write-region} seeks to that byte offset from the start
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
591 of the file and writes the data from there.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
592
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
593 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
594 for confirmation if @var{filename} names an existing file. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
595 @var{mustbenew} is the symbol @code{excl}, then @code{write-region}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
596 does not ask for confirmation, but instead it signals an error
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
597 @code{file-already-exists} if the file already exists.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
598
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
599 The test for an existing file, when @var{mustbenew} is @code{excl}, uses
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
600 a special system feature. At least for files on a local disk, there is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
601 no chance that some other program could create a file of the same name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
602 before Emacs does, without Emacs's noticing.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
603
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
604 If @var{visit} is @code{t}, then Emacs establishes an association
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
605 between the buffer and the file: the buffer is then visiting that file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
606 It also sets the last file modification time for the current buffer to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
607 @var{filename}'s modtime, and marks the buffer as not modified. This
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
608 feature is used by @code{save-buffer}, but you probably should not use
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
609 it yourself.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
610
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
611 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
612 If @var{visit} is a string, it specifies the file name to visit. This
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
613 way, you can write the data to one file (@var{filename}) while recording
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
614 the buffer as visiting another file (@var{visit}). The argument
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
615 @var{visit} is used in the echo area message and also for file locking;
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
616 @var{visit} is stored in @code{buffer-file-name}. This feature is used
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
617 to implement @code{file-precious-flag}; don't use it yourself unless you
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
618 really know what you're doing.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
619
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
620 The optional argument @var{lockname}, if non-@code{nil}, specifies the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
621 file name to use for purposes of locking and unlocking, overriding
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
622 @var{filename} and @var{visit} for that purpose.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
623
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
624 The function @code{write-region} converts the data which it writes to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
625 the appropriate file formats specified by @code{buffer-file-format}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
626 and also calls the functions in the list
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
627 @code{write-region-annotate-functions}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
628 @xref{Format Conversion}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
629
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
630 Normally, @code{write-region} displays the message @samp{Wrote
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
631 @var{filename}} in the echo area. If @var{visit} is neither @code{t}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
632 nor @code{nil} nor a string, then this message is inhibited. This
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
633 feature is useful for programs that use files for internal purposes,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
634 files that the user does not need to know about.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
635 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
636
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
637 @defmac with-temp-file file body@dots{}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
638 @anchor{Definition of with-temp-file}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
639 The @code{with-temp-file} macro evaluates the @var{body} forms with a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
640 temporary buffer as the current buffer; then, at the end, it writes the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
641 buffer contents into file @var{file}. It kills the temporary buffer
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
642 when finished, restoring the buffer that was current before the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
643 @code{with-temp-file} form. Then it returns the value of the last form
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
644 in @var{body}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
645
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
646 The current buffer is restored even in case of an abnormal exit via
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
647 @code{throw} or error (@pxref{Nonlocal Exits}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
648
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
649 See also @code{with-temp-buffer} in @ref{Definition of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
650 with-temp-buffer,, The Current Buffer}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
651 @end defmac
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
652
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
653 @node File Locks
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
654 @section File Locks
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
655 @cindex file locks
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
656 @cindex lock file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
657
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
658 When two users edit the same file at the same time, they are likely
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
659 to interfere with each other. Emacs tries to prevent this situation
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
660 from arising by recording a @dfn{file lock} when a file is being
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
661 modified. (File locks are not implemented on Microsoft systems.)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
662 Emacs can then detect the first attempt to modify a buffer visiting a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
663 file that is locked by another Emacs job, and ask the user what to do.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
664 The file lock is really a file, a symbolic link with a special name,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
665 stored in the same directory as the file you are editing.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
666
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
667 When you access files using NFS, there may be a small probability that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
668 you and another user will both lock the same file ``simultaneously.''
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
669 If this happens, it is possible for the two users to make changes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
670 simultaneously, but Emacs will still warn the user who saves second.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
671 Also, the detection of modification of a buffer visiting a file changed
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
672 on disk catches some cases of simultaneous editing; see
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
673 @ref{Modification Time}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
674
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
675 @defun file-locked-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
676 This function returns @code{nil} if the file @var{filename} is not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
677 locked. It returns @code{t} if it is locked by this Emacs process, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
678 it returns the name of the user who has locked it if it is locked by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
679 some other job.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
680
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
681 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
682 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
683 (file-locked-p "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
684 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
685 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
686 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
687 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
688
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
689 @defun lock-buffer &optional filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
690 This function locks the file @var{filename}, if the current buffer is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
691 modified. The argument @var{filename} defaults to the current buffer's
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
692 visited file. Nothing is done if the current buffer is not visiting a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
693 file, or is not modified, or if the system does not support locking.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
694 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
695
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
696 @defun unlock-buffer
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
697 This function unlocks the file being visited in the current buffer,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
698 if the buffer is modified. If the buffer is not modified, then
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
699 the file should not be locked, so this function does nothing. It also
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
700 does nothing if the current buffer is not visiting a file, or if the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
701 system does not support locking.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
702 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
703
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
704 File locking is not supported on some systems. On systems that do not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
705 support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
706 @code{file-locked-p} do nothing and return @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
707
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
708 @defun ask-user-about-lock file other-user
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
709 This function is called when the user tries to modify @var{file}, but it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
710 is locked by another user named @var{other-user}. The default
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
711 definition of this function asks the user to say what to do. The value
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
712 this function returns determines what Emacs does next:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
713
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
714 @itemize @bullet
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
715 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
716 A value of @code{t} says to grab the lock on the file. Then
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
717 this user may edit the file and @var{other-user} loses the lock.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
718
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
719 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
720 A value of @code{nil} says to ignore the lock and let this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
721 user edit the file anyway.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
722
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
723 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
724 @kindex file-locked
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
725 This function may instead signal a @code{file-locked} error, in which
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
726 case the change that the user was about to make does not take place.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
727
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
728 The error message for this error looks like this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
729
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
730 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
731 @error{} File is locked: @var{file} @var{other-user}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
732 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
733
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
734 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
735 where @code{file} is the name of the file and @var{other-user} is the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
736 name of the user who has locked the file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
737 @end itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
738
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
739 If you wish, you can replace the @code{ask-user-about-lock} function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
740 with your own version that makes the decision in another way. The code
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
741 for its usual definition is in @file{userlock.el}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
742 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
743
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
744 @node Information about Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
745 @section Information about Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
746 @cindex file, information about
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
747
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
748 The functions described in this section all operate on strings that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
749 designate file names. With a few exceptions, all the functions have
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
750 names that begin with the word @samp{file}. These functions all
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
751 return information about actual files or directories, so their
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
752 arguments must all exist as actual files or directories unless
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
753 otherwise noted.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
754
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
755 @menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
756 * Testing Accessibility:: Is a given file readable? Writable?
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
757 * Kinds of Files:: Is it a directory? A symbolic link?
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
758 * Truenames:: Eliminating symbolic links from a file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
759 * File Attributes:: How large is it? Any other names? Etc.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
760 * Locating Files:: How to find a file in standard places.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
761 @end menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
762
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
763 @node Testing Accessibility
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
764 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
765 @subsection Testing Accessibility
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
766 @cindex accessibility of a file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
767 @cindex file accessibility
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
768
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
769 These functions test for permission to access a file in specific
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
770 ways. Unless explicitly stated otherwise, they recursively follow
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
771 symbolic links for their file name arguments, at all levels (at the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
772 level of the file itself and at all levels of parent directories).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
773
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
774 @defun file-exists-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
775 This function returns @code{t} if a file named @var{filename} appears
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
776 to exist. This does not mean you can necessarily read the file, only
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
777 that you can find out its attributes. (On Unix and GNU/Linux, this is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
778 true if the file exists and you have execute permission on the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
779 containing directories, regardless of the protection of the file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
780 itself.)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
781
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
782 If the file does not exist, or if fascist access control policies
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
783 prevent you from finding the attributes of the file, this function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
784 returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
785
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
786 Directories are files, so @code{file-exists-p} returns @code{t} when
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
787 given a directory name. However, symbolic links are treated
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
788 specially; @code{file-exists-p} returns @code{t} for a symbolic link
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
789 name only if the target file exists.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
790 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
791
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
792 @defun file-readable-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
793 This function returns @code{t} if a file named @var{filename} exists
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
794 and you can read it. It returns @code{nil} otherwise.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
795
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
796 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
797 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
798 (file-readable-p "files.texi")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
799 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
800 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
801 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
802 (file-exists-p "/usr/spool/mqueue")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
803 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
804 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
805 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
806 (file-readable-p "/usr/spool/mqueue")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
807 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
808 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
809 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
810 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
811
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
812 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
813 @defun file-executable-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
814 This function returns @code{t} if a file named @var{filename} exists and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
815 you can execute it. It returns @code{nil} otherwise. On Unix and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
816 GNU/Linux, if the file is a directory, execute permission means you can
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
817 check the existence and attributes of files inside the directory, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
818 open those files if their modes permit.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
819 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
820
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
821 @defun file-writable-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
822 This function returns @code{t} if the file @var{filename} can be written
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
823 or created by you, and @code{nil} otherwise. A file is writable if the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
824 file exists and you can write it. It is creatable if it does not exist,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
825 but the specified directory does exist and you can write in that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
826 directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
827
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
828 In the third example below, @file{foo} is not writable because the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
829 parent directory does not exist, even though the user could create such
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
830 a directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
831
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
832 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
833 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
834 (file-writable-p "~/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
835 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
836 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
837 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
838 (file-writable-p "/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
839 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
840 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
841 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
842 (file-writable-p "~/no-such-dir/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
843 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
844 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
845 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
846 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
847
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
848 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
849 @defun file-accessible-directory-p dirname
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
850 This function returns @code{t} if you have permission to open existing
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
851 files in the directory whose name as a file is @var{dirname};
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
852 otherwise (or if there is no such directory), it returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
853 The value of @var{dirname} may be either a directory name (such as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
854 @file{/foo/}) or the file name of a file which is a directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
855 (such as @file{/foo}, without the final slash).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
856
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
857 Example: after the following,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
858
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
859 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
860 (file-accessible-directory-p "/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
861 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
862 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
863
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
864 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
865 we can deduce that any attempt to read a file in @file{/foo/} will
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
866 give an error.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
867 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
868
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
869 @defun access-file filename string
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
870 This function opens file @var{filename} for reading, then closes it and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
871 returns @code{nil}. However, if the open fails, it signals an error
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
872 using @var{string} as the error message text.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
873 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
874
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
875 @defun file-ownership-preserved-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
876 This function returns @code{t} if deleting the file @var{filename} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
877 then creating it anew would keep the file's owner unchanged. It also
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
878 returns @code{t} for nonexistent files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
879
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
880 If @var{filename} is a symbolic link, then, unlike the other functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
881 discussed here, @code{file-ownership-preserved-p} does @emph{not}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
882 replace @var{filename} with its target. However, it does recursively
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
883 follow symbolic links at all levels of parent directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
884 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
885
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
886 @defun file-newer-than-file-p filename1 filename2
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
887 @cindex file age
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
888 @cindex file modification time
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
889 This function returns @code{t} if the file @var{filename1} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
890 newer than file @var{filename2}. If @var{filename1} does not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
891 exist, it returns @code{nil}. If @var{filename1} does exist, but
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
892 @var{filename2} does not, it returns @code{t}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
893
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
894 In the following example, assume that the file @file{aug-19} was written
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
895 on the 19th, @file{aug-20} was written on the 20th, and the file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
896 @file{no-file} doesn't exist at all.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
897
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
898 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
899 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
900 (file-newer-than-file-p "aug-19" "aug-20")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
901 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
902 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
903 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
904 (file-newer-than-file-p "aug-20" "aug-19")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
905 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
906 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
907 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
908 (file-newer-than-file-p "aug-19" "no-file")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
909 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
910 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
911 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
912 (file-newer-than-file-p "no-file" "aug-19")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
913 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
914 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
915 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
916
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
917 You can use @code{file-attributes} to get a file's last modification
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
918 time as a list of two numbers. @xref{File Attributes}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
919 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
920
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
921 @node Kinds of Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
922 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
923 @subsection Distinguishing Kinds of Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
924
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
925 This section describes how to distinguish various kinds of files, such
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
926 as directories, symbolic links, and ordinary files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
927
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
928 @defun file-symlink-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
929 @cindex file symbolic links
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
930 If the file @var{filename} is a symbolic link, the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
931 @code{file-symlink-p} function returns the (non-recursive) link target
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
932 as a string. (Determining the file name that the link points to from
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
933 the target is nontrivial.) First, this function recursively follows
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
934 symbolic links at all levels of parent directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
935
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
936 If the file @var{filename} is not a symbolic link (or there is no such file),
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
937 @code{file-symlink-p} returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
938
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
939 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
940 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
941 (file-symlink-p "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
942 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
943 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
944 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
945 (file-symlink-p "sym-link")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
946 @result{} "foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
947 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
948 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
949 (file-symlink-p "sym-link2")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
950 @result{} "sym-link"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
951 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
952 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
953 (file-symlink-p "/bin")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
954 @result{} "/pub/bin"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
955 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
956 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
957
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
958 @c !!! file-symlink-p: should show output of ls -l for comparison
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
959 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
960
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
961 The next two functions recursively follow symbolic links at
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
962 all levels for @var{filename}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
963
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
964 @defun file-directory-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
965 This function returns @code{t} if @var{filename} is the name of an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
966 existing directory, @code{nil} otherwise.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
967
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
968 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
969 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
970 (file-directory-p "~rms")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
971 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
972 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
973 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
974 (file-directory-p "~rms/lewis/files.texi")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
975 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
976 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
977 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
978 (file-directory-p "~rms/lewis/no-such-file")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
979 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
980 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
981 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
982 (file-directory-p "$HOME")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
983 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
984 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
985 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
986 (file-directory-p
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
987 (substitute-in-file-name "$HOME"))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
988 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
989 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
990 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
991 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
992
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
993 @defun file-regular-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
994 This function returns @code{t} if the file @var{filename} exists and is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
995 a regular file (not a directory, named pipe, terminal, or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
996 other I/O device).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
997 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
998
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
999 @node Truenames
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1000 @subsection Truenames
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1001 @cindex truename (of file)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1002
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1003 @c Emacs 19 features
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1004 The @dfn{truename} of a file is the name that you get by following
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1005 symbolic links at all levels until none remain, then simplifying away
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1006 @samp{.}@: and @samp{..}@: appearing as name components. This results
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1007 in a sort of canonical name for the file. A file does not always have a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1008 unique truename; the number of distinct truenames a file has is equal to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1009 the number of hard links to the file. However, truenames are useful
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1010 because they eliminate symbolic links as a cause of name variation.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1011
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1012 @defun file-truename filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1013 The function @code{file-truename} returns the truename of the file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1014 @var{filename}. The argument must be an absolute file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1015
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1016 This function does not expand environment variables. Only
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1017 @code{substitute-in-file-name} does that. @xref{Definition of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1018 substitute-in-file-name}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1019
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1020 If you may need to follow symbolic links preceding @samp{..}@:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1021 appearing as a name component, you should make sure to call
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1022 @code{file-truename} without prior direct or indirect calls to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1023 @code{expand-file-name}, as otherwise the file name component
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1024 immediately preceding @samp{..} will be ``simplified away'' before
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1025 @code{file-truename} is called. To eliminate the need for a call to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1026 @code{expand-file-name}, @code{file-truename} handles @samp{~} in the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1027 same way that @code{expand-file-name} does. @xref{File Name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1028 Expansion,, Functions that Expand Filenames}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1029 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1030
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1031 @defun file-chase-links filename &optional limit
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1032 This function follows symbolic links, starting with @var{filename},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1033 until it finds a file name which is not the name of a symbolic link.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1034 Then it returns that file name. This function does @emph{not} follow
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1035 symbolic links at the level of parent directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1036
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1037 If you specify a number for @var{limit}, then after chasing through
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1038 that many links, the function just returns what it has even if that is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1039 still a symbolic link.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1040 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1041
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1042 To illustrate the difference between @code{file-chase-links} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1043 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1044 the directory @file{/home/foo}, and @file{/home/foo/hello} is an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1045 ordinary file (or at least, not a symbolic link) or nonexistent. Then
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1046 we would have:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1047
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1048 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1049 (file-chase-links "/usr/foo/hello")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1050 ;; @r{This does not follow the links in the parent directories.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1051 @result{} "/usr/foo/hello"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1052 (file-truename "/usr/foo/hello")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1053 ;; @r{Assuming that @file{/home} is not a symbolic link.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1054 @result{} "/home/foo/hello"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1055 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1056
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1057 @xref{Buffer File Name}, for related information.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1058
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1059 @node File Attributes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1060 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1061 @subsection Other Information about Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1062
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1063 This section describes the functions for getting detailed information
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1064 about a file, other than its contents. This information includes the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1065 mode bits that control access permission, the owner and group numbers,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1066 the number of names, the inode number, the size, and the times of access
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1067 and modification.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1068
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1069 @defun file-modes filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1070 @cindex permission
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1071 @cindex file attributes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1072 This function returns the mode bits of @var{filename}, as an integer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1073 The mode bits are also called the file permissions, and they specify
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1074 access control in the usual Unix fashion. If the low-order bit is 1,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1075 then the file is executable by all users, if the second-lowest-order bit
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1076 is 1, then the file is writable by all users, etc.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1077
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1078 The highest value returnable is 4095 (7777 octal), meaning that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1079 everyone has read, write, and execute permission, that the @acronym{SUID} bit
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1080 is set for both others and group, and that the sticky bit is set.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1081
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1082 If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1083
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1084 This function recursively follows symbolic links at all levels.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1085
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1086 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1087 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1088 (file-modes "~/junk/diffs")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1089 @result{} 492 ; @r{Decimal integer.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1090 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1091 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1092 (format "%o" 492)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1093 @result{} "754" ; @r{Convert to octal.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1094 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1095
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1096 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1097 (set-file-modes "~/junk/diffs" 438)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1098 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1099 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1100
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1101 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1102 (format "%o" 438)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1103 @result{} "666" ; @r{Convert to octal.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1104 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1105
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1106 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1107 % ls -l diffs
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1108 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1109 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1110 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1111 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1112
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1113 If the @var{filename} argument to the next two functions is a symbolic
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1114 link, then these function do @emph{not} replace it with its target.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1115 However, they both recursively follow symbolic links at all levels of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1116 parent directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1117
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1118 @defun file-nlinks filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1119 This functions returns the number of names (i.e., hard links) that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1120 file @var{filename} has. If the file does not exist, then this function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1121 returns @code{nil}. Note that symbolic links have no effect on this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1122 function, because they are not considered to be names of the files they
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1123 link to.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1124
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1125 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1126 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1127 % ls -l foo*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1128 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1129 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1130 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1131
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1132 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1133 (file-nlinks "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1134 @result{} 2
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1135 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1136 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1137 (file-nlinks "doesnt-exist")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1138 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1139 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1140 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1141 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1142
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1143 @defun file-attributes filename &optional id-format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1144 @anchor{Definition of file-attributes}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1145 This function returns a list of attributes of file @var{filename}. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1146 the specified file cannot be opened, it returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1147 The optional parameter @var{id-format} specifies the preferred format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1148 of attributes @acronym{UID} and @acronym{GID} (see below)---the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1149 valid values are @code{'string} and @code{'integer}. The latter is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1150 the default, but we plan to change that, so you should specify a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1151 non-@code{nil} value for @var{id-format} if you use the returned
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1152 @acronym{UID} or @acronym{GID}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1153
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1154 The elements of the list, in order, are:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1155
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1156 @enumerate 0
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1157 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1158 @code{t} for a directory, a string for a symbolic link (the name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1159 linked to), or @code{nil} for a text file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1160
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1161 @c Wordy so as to prevent an overfull hbox. --rjc 15mar92
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1162 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1163 The number of names the file has. Alternate names, also known as hard
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1164 links, can be created by using the @code{add-name-to-file} function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1165 (@pxref{Changing Files}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1166
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1167 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1168 The file's @acronym{UID}, normally as a string. However, if it does
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1169 not correspond to a named user, the value is an integer or a floating
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1170 point number.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1171
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1172 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1173 The file's @acronym{GID}, likewise.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1174
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1175 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1176 The time of last access, as a list of two integers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1177 The first integer has the high-order 16 bits of time,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1178 the second has the low 16 bits. (This is similar to the
105460
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1179 value of @code{current-time}; see @ref{Time of Day}.) Note that on
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1180 some FAT-based filesystems, only the date of last access is recorded,
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1181 so this time will always hold the midnight of the day of last access.
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1182
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1183 @cindex modification time of file
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1184 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1185 The time of last modification as a list of two integers (as above).
105460
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1186 This is the last time when the file's contents were modified.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1187
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1188 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1189 The time of last status change as a list of two integers (as above).
105460
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1190 This is the time of the last change to the file's access mode bits,
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1191 its owner and group, and other information recorded in the filesystem
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1192 for the file, beyond the file's contents.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1193
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1194 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1195 The size of the file in bytes. If the size is too large to fit in a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1196 Lisp integer, this is a floating point number.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1197
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1198 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1199 The file's modes, as a string of ten letters or dashes,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1200 as in @samp{ls -l}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1201
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1202 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1203 @code{t} if the file's @acronym{GID} would change if file were
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1204 deleted and recreated; @code{nil} otherwise.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1205
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1206 @item
105460
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1207 The file's inode number. If possible, this is an integer. If the
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1208 inode number is too large to be represented as an integer in Emacs
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1209 Lisp, but still fits into a 32-bit integer, then the value has the
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1210 form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1211 bits. If the inode is wider than 32 bits, the value is of the form
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1212 @code{(@var{high} @var{middle} . @var{low})}, where @code{high} holds
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1213 the high 24 bits, @var{middle} the next 24 bits, and @var{low} the low
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1214 16 bits.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1215
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1216 @item
105460
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1217 The filesystem number of the device that the file is on. Depending on
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1218 the magnitude of the value, this can be either an integer or a cons
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1219 cell, in the same manner as the inode number. This element and the
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1220 file's inode number together give enough information to distinguish
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1221 any two files on the system---no two files can have the same values
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1222 for both of these numbers.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1223 @end enumerate
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1224
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1225 For example, here are the file attributes for @file{files.texi}:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1226
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1227 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1228 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1229 (file-attributes "files.texi" 'string)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1230 @result{} (nil 1 "lh" "users"
105460
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1231 (19145 42977)
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1232 (19141 59576)
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1233 (18340 17300)
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1234 122295 "-rw-rw-rw-"
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1235 nil (5888 2 . 43978)
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1236 (15479 . 46724))
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1237 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1238 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1239
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1240 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1241 and here is how the result is interpreted:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1242
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1243 @table @code
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1244 @item nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1245 is neither a directory nor a symbolic link.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1246
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1247 @item 1
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1248 has only one name (the name @file{files.texi} in the current default
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1249 directory).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1250
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1251 @item "lh"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1252 is owned by the user with name "lh".
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1253
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1254 @item "users"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1255 is in the group with name "users".
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1256
105460
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1257 @item (19145 42977)
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1258 was last accessed on Oct 5 2009, at 10:01:37.
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1259
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1260 @item (19141 59576)
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1261 last had its contents modified on Oct 2 2009, at 13:49:12.
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1262
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1263 @item (18340 17300)
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1264 last had its status changed on Feb 2 2008, at 12:19:00.
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1265
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1266 @item 122295
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1267 is 122295 bytes long. (It may not contain 122295 characters, though,
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1268 if some of the bytes belong to multibyte sequences, and also if the
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1269 end-of-line format is CR-LF.)
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1270
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1271 @item "-rw-rw-rw-"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1272 has a mode of read and write access for the owner, group, and world.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1273
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1274 @item nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1275 would retain the same @acronym{GID} if it were recreated.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1276
105460
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1277 @item (5888 2 . 43978)
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1278 has an inode number of 6473924464520138.
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1279
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1280 @item (15479 . 46724)
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
1281 is on the file-system device whose number is 1014478468.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1282 @end table
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1283 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1284
102832
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1285 @cindex MS-DOS and file modes
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1286 @cindex file modes and MS-DOS
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1287 On MS-DOS, there is no such thing as an ``executable'' file mode bit.
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1288 So Emacs considers a file executable if its name ends in one of the
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1289 standard executable extensions, such as @file{.com}, @file{.bat},
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1290 @file{.exe}, and some others. Files that begin with the Unix-standard
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1291 @samp{#!} signature, such as shell and Perl scripts, are also considered
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1292 as executable files. This is reflected in the values returned by
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1293 @code{file-modes} and @code{file-attributes}. Directories are also
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1294 reported with executable bit set, for compatibility with Unix.
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
1295
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1296 @node Locating Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1297 @subsection How to Locate Files in Standard Places
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1298 @cindex locate file in path
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1299 @cindex find file in path
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1300
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1301 This section explains how to search for a file in a list of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1302 directories (a @dfn{path}). One example is when you need to look for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1303 a program's executable file, e.g., to find out whether a given program
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1304 is installed on the user's system. Another example is the search for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1305 Lisp libraries (@pxref{Library Search}). Such searches generally need
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1306 to try various possible file name extensions, in addition to various
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1307 possible directories. Emacs provides a function for such a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1308 generalized search for a file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1309
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1310 @defun locate-file filename path &optional suffixes predicate
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1311 This function searches for a file whose name is @var{filename} in a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1312 list of directories given by @var{path}, trying the suffixes in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1313 @var{suffixes}. If it finds such a file, it returns the full
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1314 @dfn{absolute file name} of the file (@pxref{Relative File Names});
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1315 otherwise it returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1316
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1317 The optional argument @var{suffixes} gives the list of file-name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1318 suffixes to append to @var{filename} when searching.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1319 @code{locate-file} tries each possible directory with each of these
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1320 suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1321 are no suffixes, and @var{filename} is used only as-is. Typical
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1322 values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1323 Creation, exec-suffixes}), @code{load-suffixes},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1324 @code{load-file-rep-suffixes} and the return value of the function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1325 @code{get-load-suffixes} (@pxref{Load Suffixes}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1326
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1327 Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1328 Creation, exec-path}) when looking for executable programs or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1329 @code{load-path} (@pxref{Library Search, load-path}) when looking for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1330 Lisp files. If @var{filename} is absolute, @var{path} has no effect,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1331 but the suffixes in @var{suffixes} are still tried.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1332
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1333 The optional argument @var{predicate}, if non-@code{nil}, specifies
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1334 the predicate function to use for testing whether a candidate file is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1335 suitable. The predicate function is passed the candidate file name as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1336 its single argument. If @var{predicate} is @code{nil} or unspecified,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1337 @code{locate-file} uses @code{file-readable-p} as the default
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1338 predicate. Useful non-default predicates include
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1339 @code{file-executable-p}, @code{file-directory-p}, and other
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1340 predicates described in @ref{Kinds of Files}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1341
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1342 For compatibility, @var{predicate} can also be one of the symbols
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1343 @code{executable}, @code{readable}, @code{writable}, @code{exists}, or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1344 a list of one or more of these symbols.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1345 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1346
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1347 @defun executable-find program
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1348 This function searches for the executable file of the named
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1349 @var{program} and returns the full absolute name of the executable,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1350 including its file-name extensions, if any. It returns @code{nil} if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1351 the file is not found. The functions searches in all the directories
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1352 in @code{exec-path} and tries all the file-name extensions in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1353 @code{exec-suffixes}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1354 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1355
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1356 @node Changing Files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1357 @section Changing File Names and Attributes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1358 @c @cindex renaming files Duplicates rename-file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1359 @cindex copying files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1360 @cindex deleting files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1361 @cindex linking files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1362 @cindex setting modes of files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1363
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1364 The functions in this section rename, copy, delete, link, and set the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1365 modes of files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1366
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1367 In the functions that have an argument @var{newname}, if a file by the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1368 name of @var{newname} already exists, the actions taken depend on the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1369 value of the argument @var{ok-if-already-exists}:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1370
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1371 @itemize @bullet
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1372 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1373 Signal a @code{file-already-exists} error if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1374 @var{ok-if-already-exists} is @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1375
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1376 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1377 Request confirmation if @var{ok-if-already-exists} is a number.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1378
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1379 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1380 Replace the old file without confirmation if @var{ok-if-already-exists}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1381 is any other value.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1382 @end itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1383
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1384 The next four commands all recursively follow symbolic links at all
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1385 levels of parent directories for their first argument, but, if that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1386 argument is itself a symbolic link, then only @code{copy-file}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1387 replaces it with its (recursive) target.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1388
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1389 @deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1390 @cindex file with multiple names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1391 @cindex file hard link
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1392 This function gives the file named @var{oldname} the additional name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1393 @var{newname}. This means that @var{newname} becomes a new ``hard
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1394 link'' to @var{oldname}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1395
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1396 In the first part of the following example, we list two files,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1397 @file{foo} and @file{foo3}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1398
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1399 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1400 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1401 % ls -li fo*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1402 81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1403 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1404 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1405 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1406
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1407 Now we create a hard link, by calling @code{add-name-to-file}, then list
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1408 the files again. This shows two names for one file, @file{foo} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1409 @file{foo2}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1410
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1411 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1412 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1413 (add-name-to-file "foo" "foo2")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1414 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1415 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1416
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1417 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1418 % ls -li fo*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1419 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1420 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1421 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1422 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1423 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1424
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1425 Finally, we evaluate the following:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1426
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1427 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1428 (add-name-to-file "foo" "foo3" t)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1429 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1430
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1431 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1432 and list the files again. Now there are three names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1433 for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1434 contents of @file{foo3} are lost.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1435
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1436 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1437 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1438 (add-name-to-file "foo1" "foo3")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1439 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1440 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1441
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1442 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1443 % ls -li fo*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1444 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1445 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1446 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1447 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1448 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1449
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1450 This function is meaningless on operating systems where multiple names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1451 for one file are not allowed. Some systems implement multiple names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1452 by copying the file instead.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1453
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1454 See also @code{file-nlinks} in @ref{File Attributes}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1455 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1456
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1457 @deffn Command rename-file filename newname &optional ok-if-already-exists
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1458 This command renames the file @var{filename} as @var{newname}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1459
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1460 If @var{filename} has additional names aside from @var{filename}, it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1461 continues to have those names. In fact, adding the name @var{newname}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1462 with @code{add-name-to-file} and then deleting @var{filename} has the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1463 same effect as renaming, aside from momentary intermediate states.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1464 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1465
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1466 @deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1467 This command copies the file @var{oldname} to @var{newname}. An
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1468 error is signaled if @var{oldname} does not exist. If @var{newname}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1469 names a directory, it copies @var{oldname} into that directory,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1470 preserving its final name component.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1471
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1472 If @var{time} is non-@code{nil}, then this function gives the new file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1473 the same last-modified time that the old one has. (This works on only
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1474 some operating systems.) If setting the time gets an error,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1475 @code{copy-file} signals a @code{file-date-error} error. In an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1476 interactive call, a prefix argument specifies a non-@code{nil} value
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1477 for @var{time}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1478
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1479 This function copies the file modes, too.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1480
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1481 If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1482 system decide the user and group ownership of the new file (this is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1483 usually set to the user running Emacs). If @var{preserve-uid-gid} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1484 non-@code{nil}, we attempt to copy the user and group ownership of the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1485 file. This works only on some operating systems, and only if you have
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1486 the correct permissions to do so.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1487 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1488
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1489 @deffn Command make-symbolic-link filename newname &optional ok-if-exists
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1490 @pindex ln
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1491 @kindex file-already-exists
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1492 This command makes a symbolic link to @var{filename}, named
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1493 @var{newname}. This is like the shell command @samp{ln -s
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1494 @var{filename} @var{newname}}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1495
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1496 This function is not available on systems that don't support symbolic
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1497 links.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1498 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1499
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1500 @deffn Command delete-file filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1501 @pindex rm
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1502 This command deletes the file @var{filename}, like the shell command
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1503 @samp{rm @var{filename}}. If the file has multiple names, it continues
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1504 to exist under the other names.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1505
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1506 A suitable kind of @code{file-error} error is signaled if the file does
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1507 not exist, or is not deletable. (On Unix and GNU/Linux, a file is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1508 deletable if its directory is writable.)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1509
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1510 If @var{filename} is a symbolic link, @code{delete-file} does not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1511 replace it with its target, but it does follow symbolic links at all
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1512 levels of parent directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1513
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1514 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1515 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1516
98831
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1517 @deffn Command set-file-modes filename mode
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1518 This function sets mode bits of @var{filename} to @var{mode} (which
98831
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1519 must be an integer when the function is called non-interactively).
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1520 Only the low 12 bits of @var{mode} are used.
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1521
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1522 Interactively, @var{mode} is read from the minibuffer using
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1523 @code{read-file-modes}, which accepts mode bits either as a number or
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1524 as a character string representing the mode bits symbolically. See
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1525 the description of @code{read-file-modes} below for the supported
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1526 forms of symbolic notation for mode bits.
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1527
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1528 This function recursively follows symbolic links at all levels for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1529 @var{filename}.
98831
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1530 @end deffn
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1531
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1532 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1533 @defun set-default-file-modes mode
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1534 @cindex umask
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1535 This function sets the default file protection for new files created by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1536 Emacs and its subprocesses. Every file created with Emacs initially has
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1537 this protection, or a subset of it (@code{write-region} will not give a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1538 file execute permission even if the default file protection allows
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1539 execute permission). On Unix and GNU/Linux, the default protection is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1540 the bitwise complement of the ``umask'' value.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1541
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1542 The argument @var{mode} must be an integer. On most systems, only the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1543 low 9 bits of @var{mode} are meaningful. You can use the Lisp construct
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1544 for octal character codes to enter @var{mode}; for example,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1545
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1546 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1547 (set-default-file-modes ?\644)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1548 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1549
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1550 Saving a modified version of an existing file does not count as creating
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1551 the file; it preserves the existing file's mode, whatever that is. So
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1552 the default file protection has no effect.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1553 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1554
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1555 @defun default-file-modes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1556 This function returns the current default protection value.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1557 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1558
98831
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1559 @defun read-file-modes &optional prompt base-file
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1560 This function reads file mode bits from the minibuffer. The optional
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1561 argument @var{prompt} specifies a non-default prompt. Second optional
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1562 argument @var{base-file} is the name of a file on whose permissions to
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1563 base the mode bits that this function returns, if what the user types
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1564 specifies mode bits relative to permissions of an existing file.
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1565
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1566 If user input represents an octal number, this function returns that
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1567 number. If it is a complete symbolic specification of mode bits, as
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1568 in @code{"u=rwx"}, the function converts it to the equivalent numeric
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1569 value using @code{file-modes-symbolic-to-number} and returns the
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1570 result. If the specification is relative, as in @code{"o+g"}, then
98841
b7164f9c80bc (Changing Files): Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents: 98831
diff changeset
1571 the permissions on which the specification is based are taken from the
98831
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1572 mode bits of @var{base-file}. If @var{base-file} is omitted or
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1573 @code{nil}, the function uses @code{0} as the base mode bits. The
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1574 complete and relative specifications can be combined, as in
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1575 @code{"u+r,g+rx,o+r,g-w"}. @xref{File Permissions,,, coreutils, The
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1576 @sc{gnu} @code{Coreutils} Manual}, for detailed description of
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1577 symbolic mode bits specifications.
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1578 @end defun
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1579
98927
b5ddab370f08 Don't use @deffn Subroutine.
Eli Zaretskii <eliz@gnu.org>
parents: 98841
diff changeset
1580 @defun file-modes-symbolic-to-number modes &optional base-modes
98831
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1581 This subroutine converts a symbolic specification of file mode bits in
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1582 @var{modes} into the equivalent numeric value. If the symbolic
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1583 specification is based on an existing file, that file's mode bits are
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1584 taken from the optional argument @var{base-modes}; if that argument is
99912
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
1585 omitted or @code{nil}, it defaults to zero, i.e.@: no access rights at
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
1586 all.
98927
b5ddab370f08 Don't use @deffn Subroutine.
Eli Zaretskii <eliz@gnu.org>
parents: 98841
diff changeset
1587 @end defun
98831
52967c87bfca (Changing Files): Document symbolic input of file modes to `set-file-modes'.
Eli Zaretskii <eliz@gnu.org>
parents: 97142
diff changeset
1588
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1589 @defun set-file-times filename &optional time
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1590 This function sets the access and modification times of @var{filename}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1591 to @var{time}. The return value is @code{t} if the times are successfully
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1592 set, otherwise it is @code{nil}. @var{time} defaults to the current
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1593 time and must be in the format returned by @code{current-time}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1594 (@pxref{Time of Day}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1595 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1596
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1597 @node File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1598 @section File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1599 @cindex file names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1600
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1601 Files are generally referred to by their names, in Emacs as elsewhere.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1602 File names in Emacs are represented as strings. The functions that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1603 operate on a file all expect a file name argument.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1604
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1605 In addition to operating on files themselves, Emacs Lisp programs
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1606 often need to operate on file names; i.e., to take them apart and to use
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1607 part of a name to construct related file names. This section describes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1608 how to manipulate file names.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1609
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1610 The functions in this section do not actually access files, so they
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1611 can operate on file names that do not refer to an existing file or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1612 directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1613
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1614 On MS-DOS and MS-Windows, these functions (like the function that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1615 actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1616 where backslashes separate the components, as well as Unix syntax; but
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1617 they always return Unix syntax. This enables Lisp programs to specify
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1618 file names in Unix syntax and work properly on all systems without
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1619 change.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1620
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1621 @menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1622 * File Name Components:: The directory part of a file name, and the rest.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1623 * Relative File Names:: Some file names are relative to a current directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1624 * Directory Names:: A directory's name as a directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1625 is different from its name as a file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1626 * File Name Expansion:: Converting relative file names to absolute ones.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1627 * Unique File Names:: Generating names for temporary files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1628 * File Name Completion:: Finding the completions for a given file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1629 * Standard File Names:: If your package uses a fixed file name,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1630 how to handle various operating systems simply.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1631 @end menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1632
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1633 @node File Name Components
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1634 @subsection File Name Components
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1635 @cindex directory part (of file name)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1636 @cindex nondirectory part (of file name)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1637 @cindex version number (in file name)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1638
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1639 The operating system groups files into directories. To specify a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1640 file, you must specify the directory and the file's name within that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1641 directory. Therefore, Emacs considers a file name as having two main
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1642 parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1643 (or @dfn{file name within the directory}). Either part may be empty.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1644 Concatenating these two parts reproduces the original file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1645
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1646 On most systems, the directory part is everything up to and including
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1647 the last slash (backslash is also allowed in input on MS-DOS or
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1648 MS-Windows); the nondirectory part is the rest.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1649
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1650 For some purposes, the nondirectory part is further subdivided into
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1651 the name proper and the @dfn{version number}. On most systems, only
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1652 backup files have version numbers in their names.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1653
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1654 @defun file-name-directory filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1655 This function returns the directory part of @var{filename}, as a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1656 directory name (@pxref{Directory Names}), or @code{nil} if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1657 @var{filename} does not include a directory part.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1658
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1659 On GNU and Unix systems, a string returned by this function always
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1660 ends in a slash. On MS-DOS it can also end in a colon.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1661
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1662 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1663 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1664 (file-name-directory "lewis/foo") ; @r{Unix example}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1665 @result{} "lewis/"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1666 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1667 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1668 (file-name-directory "foo") ; @r{Unix example}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1669 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1670 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1671 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1672 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1673
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1674 @defun file-name-nondirectory filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1675 This function returns the nondirectory part of @var{filename}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1676
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1677 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1678 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1679 (file-name-nondirectory "lewis/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1680 @result{} "foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1681 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1682 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1683 (file-name-nondirectory "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1684 @result{} "foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1685 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1686 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1687 (file-name-nondirectory "lewis/")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1688 @result{} ""
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1689 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1690 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1691 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1692
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1693 @defun file-name-sans-versions filename &optional keep-backup-version
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1694 This function returns @var{filename} with any file version numbers,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1695 backup version numbers, or trailing tildes discarded.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1696
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1697 If @var{keep-backup-version} is non-@code{nil}, then true file version
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1698 numbers understood as such by the file system are discarded from the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1699 return value, but backup version numbers are kept.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1700
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1701 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1702 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1703 (file-name-sans-versions "~rms/foo.~1~")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1704 @result{} "~rms/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1705 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1706 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1707 (file-name-sans-versions "~rms/foo~")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1708 @result{} "~rms/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1709 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1710 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1711 (file-name-sans-versions "~rms/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1712 @result{} "~rms/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1713 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1714 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1715 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1716
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1717 @defun file-name-extension filename &optional period
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1718 This function returns @var{filename}'s final ``extension,'' if any,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1719 after applying @code{file-name-sans-versions} to remove any
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1720 version/backup part. The extension, in a file name, is the part that
99526
5e92b1aa0a1d (File Name Components): Fix file-name-extension documentation.
Lute Kamstra <lute@gnu.org>
parents: 99477
diff changeset
1721 follows the last @samp{.} in the last name component (minus any
5e92b1aa0a1d (File Name Components): Fix file-name-extension documentation.
Lute Kamstra <lute@gnu.org>
parents: 99477
diff changeset
1722 version/backup part).
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1723
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1724 This function returns @code{nil} for extensionless file names such as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1725 @file{foo}. It returns @code{""} for null extensions, as in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1726 @file{foo.}. If the last component of a file name begins with a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1727 @samp{.}, that @samp{.} doesn't count as the beginning of an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1728 extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1729 @samp{.emacs}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1730
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1731 If @var{period} is non-@code{nil}, then the returned value includes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1732 the period that delimits the extension, and if @var{filename} has no
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1733 extension, the value is @code{""}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1734 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1735
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1736 @defun file-name-sans-extension filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1737 This function returns @var{filename} minus its extension, if any. The
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1738 version/backup part, if present, is only removed if the file has an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1739 extension. For example,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1740
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1741 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1742 (file-name-sans-extension "foo.lose.c")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1743 @result{} "foo.lose"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1744 (file-name-sans-extension "big.hack/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1745 @result{} "big.hack/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1746 (file-name-sans-extension "/my/home/.emacs")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1747 @result{} "/my/home/.emacs"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1748 (file-name-sans-extension "/my/home/.emacs.el")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1749 @result{} "/my/home/.emacs"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1750 (file-name-sans-extension "~/foo.el.~3~")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1751 @result{} "~/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1752 (file-name-sans-extension "~/foo.~3~")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1753 @result{} "~/foo.~3~"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1754 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1755
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1756 Note that the @samp{.~3~} in the two last examples is the backup part,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1757 not an extension.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1758 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1759
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1760 @ignore
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1761 Andrew Innes says that this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1762
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1763 @c @defvar directory-sep-char
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1764 This variable holds the character that Emacs normally uses to separate
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1765 file name components. The default value is @code{?/}, but on MS-Windows
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1766 you can set it to @code{?\\}; then the functions that transform file names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1767 use backslashes in their output.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1768
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1769 File names using backslashes work as input to Lisp primitives even on
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1770 MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1771 value of @code{?/}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1772 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1773 @end ignore
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1774
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1775 @node Relative File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1776 @subsection Absolute and Relative File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1777 @cindex absolute file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1778 @cindex relative file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1779
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1780 All the directories in the file system form a tree starting at the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1781 root directory. A file name can specify all the directory names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1782 starting from the root of the tree; then it is called an @dfn{absolute}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1783 file name. Or it can specify the position of the file in the tree
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1784 relative to a default directory; then it is called a @dfn{relative} file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1785 name. On Unix and GNU/Linux, an absolute file name starts with a slash
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1786 or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1787 MS-Windows, an absolute file name starts with a slash or a backslash, or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1788 with a drive specification @samp{@var{x}:/}, where @var{x} is the
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1789 @dfn{drive letter}.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1790
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1791 @defun file-name-absolute-p filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1792 This function returns @code{t} if file @var{filename} is an absolute
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1793 file name, @code{nil} otherwise.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1794
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1795 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1796 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1797 (file-name-absolute-p "~rms/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1798 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1799 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1800 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1801 (file-name-absolute-p "rms/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1802 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1803 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1804 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1805 (file-name-absolute-p "/user/rms/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1806 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1807 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1808 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1809 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1810
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1811 Given a possibly relative file name, you can convert it to an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1812 absolute name using @code{expand-file-name} (@pxref{File Name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1813 Expansion}). This function converts absolute file names to relative
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1814 names:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1815
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1816 @defun file-relative-name filename &optional directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1817 This function tries to return a relative name that is equivalent to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1818 @var{filename}, assuming the result will be interpreted relative to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1819 @var{directory} (an absolute directory name or directory file name).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1820 If @var{directory} is omitted or @code{nil}, it defaults to the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1821 current buffer's default directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1822
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1823 On some operating systems, an absolute file name begins with a device
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1824 name. On such systems, @var{filename} has no relative equivalent based
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1825 on @var{directory} if they start with two different device names. In
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1826 this case, @code{file-relative-name} returns @var{filename} in absolute
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1827 form.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1828
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1829 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1830 (file-relative-name "/foo/bar" "/foo/")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1831 @result{} "bar"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1832 (file-relative-name "/foo/bar" "/hack/")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1833 @result{} "../foo/bar"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1834 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1835 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1836
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1837 @node Directory Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1838 @comment node-name, next, previous, up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1839 @subsection Directory Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1840 @cindex directory name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1841 @cindex file name of directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1842
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1843 A @dfn{directory name} is the name of a directory. A directory is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1844 actually a kind of file, so it has a file name, which is related to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1845 the directory name but not identical to it. (This is not quite the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1846 same as the usual Unix terminology.) These two different names for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1847 the same entity are related by a syntactic transformation. On GNU and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1848 Unix systems, this is simple: a directory name ends in a slash,
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1849 whereas the directory's name as a file lacks that slash. On MS-DOS
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1850 the relationship is more complicated.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1851
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1852 The difference between a directory name and its name as a file is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1853 subtle but crucial. When an Emacs variable or function argument is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1854 described as being a directory name, a file name of a directory is not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1855 acceptable. When @code{file-name-directory} returns a string, that is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1856 always a directory name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1857
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1858 The following two functions convert between directory names and file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1859 names. They do nothing special with environment variable substitutions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1860 such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1861
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1862 @defun file-name-as-directory filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1863 This function returns a string representing @var{filename} in a form
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1864 that the operating system will interpret as the name of a directory. On
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1865 most systems, this means appending a slash to the string (if it does not
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1866 already end in one).
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1867
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1868 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1869 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1870 (file-name-as-directory "~rms/lewis")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1871 @result{} "~rms/lewis/"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1872 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1873 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1874 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1875
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1876 @defun directory-file-name dirname
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1877 This function returns a string representing @var{dirname} in a form that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1878 the operating system will interpret as the name of a file. On most
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1879 systems, this means removing the final slash (or backslash) from the
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
1880 string.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1881
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1882 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1883 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1884 (directory-file-name "~lewis/")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1885 @result{} "~lewis"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1886 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1887 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1888 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1889
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1890 Given a directory name, you can combine it with a relative file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1891 using @code{concat}:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1892
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1893 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1894 (concat @var{dirname} @var{relfile})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1895 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1896
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1897 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1898 Be sure to verify that the file name is relative before doing that.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1899 If you use an absolute file name, the results could be syntactically
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1900 invalid or refer to the wrong file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1901
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1902 If you want to use a directory file name in making such a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1903 combination, you must first convert it to a directory name using
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1904 @code{file-name-as-directory}:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1905
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1906 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1907 (concat (file-name-as-directory @var{dirfile}) @var{relfile})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1908 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1909
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1910 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1911 Don't try concatenating a slash by hand, as in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1912
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1913 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1914 ;;; @r{Wrong!}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1915 (concat @var{dirfile} "/" @var{relfile})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1916 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1917
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1918 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1919 because this is not portable. Always use
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1920 @code{file-name-as-directory}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1921
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1922 @cindex directory name abbreviation
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1923 Directory name abbreviations are useful for directories that are
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1924 normally accessed through symbolic links. Sometimes the users recognize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1925 primarily the link's name as ``the name'' of the directory, and find it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1926 annoying to see the directory's ``real'' name. If you define the link
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1927 name as an abbreviation for the ``real'' name, Emacs shows users the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1928 abbreviation instead.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1929
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103264
diff changeset
1930 @defopt directory-abbrev-alist
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1931 The variable @code{directory-abbrev-alist} contains an alist of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1932 abbreviations to use for file directories. Each element has the form
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1933 @code{(@var{from} . @var{to})}, and says to replace @var{from} with
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1934 @var{to} when it appears in a directory name. The @var{from} string is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1935 actually a regular expression; it should always start with @samp{^}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1936 The @var{to} string should be an ordinary absolute directory name. Do
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1937 not use @samp{~} to stand for a home directory in that string. The
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1938 function @code{abbreviate-file-name} performs these substitutions.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1939
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1940 You can set this variable in @file{site-init.el} to describe the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1941 abbreviations appropriate for your site.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1942
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1943 Here's an example, from a system on which file system @file{/home/fsf}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1944 and so on are normally accessed through symbolic links named @file{/fsf}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1945 and so on.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1946
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1947 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1948 (("^/home/fsf" . "/fsf")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1949 ("^/home/gp" . "/gp")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1950 ("^/home/gd" . "/gd"))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1951 @end example
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103264
diff changeset
1952 @end defopt
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1953
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1954 To convert a directory name to its abbreviation, use this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1955 function:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1956
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1957 @defun abbreviate-file-name filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1958 @anchor{Definition of abbreviate-file-name}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1959 This function applies abbreviations from @code{directory-abbrev-alist}
105506
29b5ee370673 (Directory Names) <abbreviate-file-name>: Document that root home
Eli Zaretskii <eliz@gnu.org>
parents: 105470
diff changeset
1960 to its argument, and also substitutes @samp{~} for the user's home
29b5ee370673 (Directory Names) <abbreviate-file-name>: Document that root home
Eli Zaretskii <eliz@gnu.org>
parents: 105470
diff changeset
1961 directory if the argument names a file in the home directory or one of
29b5ee370673 (Directory Names) <abbreviate-file-name>: Document that root home
Eli Zaretskii <eliz@gnu.org>
parents: 105470
diff changeset
1962 its subdirectories. (If the home directory is a root directory, it is
29b5ee370673 (Directory Names) <abbreviate-file-name>: Document that root home
Eli Zaretskii <eliz@gnu.org>
parents: 105470
diff changeset
1963 not replaced with @samp{~}, because this does not make the result
29b5ee370673 (Directory Names) <abbreviate-file-name>: Document that root home
Eli Zaretskii <eliz@gnu.org>
parents: 105470
diff changeset
1964 shorter on many systems.) You can use it for directory names and for
29b5ee370673 (Directory Names) <abbreviate-file-name>: Document that root home
Eli Zaretskii <eliz@gnu.org>
parents: 105470
diff changeset
1965 file names, because it recognizes abbreviations even as part of the
29b5ee370673 (Directory Names) <abbreviate-file-name>: Document that root home
Eli Zaretskii <eliz@gnu.org>
parents: 105470
diff changeset
1966 name.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1967 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1968
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1969 @node File Name Expansion
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1970 @subsection Functions that Expand Filenames
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1971 @cindex expansion of file names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1972
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1973 @dfn{Expansion} of a file name means converting a relative file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1974 to an absolute one. Since this is done relative to a default directory,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1975 you must specify the default directory name as well as the file name to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1976 be expanded. Expansion also simplifies file names by eliminating
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1977 redundancies such as @file{./} and @file{@var{name}/../}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1978
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1979 @defun expand-file-name filename &optional directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1980 This function converts @var{filename} to an absolute file name. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1981 @var{directory} is supplied, it is the default directory to start with
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1982 if @var{filename} is relative. (The value of @var{directory} should
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1983 itself be an absolute directory name or directory file name; it may
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1984 start with @samp{~}.) Otherwise, the current buffer's value of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1985 @code{default-directory} is used. For example:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1986
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1987 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1988 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1989 (expand-file-name "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1990 @result{} "/xcssun/users/rms/lewis/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1991 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1992 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1993 (expand-file-name "../foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1994 @result{} "/xcssun/users/rms/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1995 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1996 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1997 (expand-file-name "foo" "/usr/spool/")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1998 @result{} "/usr/spool/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
1999 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2000 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2001 (expand-file-name "$HOME/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2002 @result{} "/xcssun/users/rms/lewis/$HOME/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2003 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2004 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2005
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2006 If the part of the combined file name before the first slash is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2007 @samp{~}, it expands to the value of the @env{HOME} environment
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2008 variable (usually your home directory). If the part before the first
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2009 slash is @samp{~@var{user}} and if @var{user} is a valid login name,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2010 it expands to @var{user}'s home directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2011
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2012 Filenames containing @samp{.} or @samp{..} are simplified to their
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2013 canonical form:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2014
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2015 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2016 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2017 (expand-file-name "bar/../foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2018 @result{} "/xcssun/users/rms/lewis/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2019 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2020 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2021
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2022 In some cases, a leading @samp{..} component can remain in the output:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2023
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2024 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2025 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2026 (expand-file-name "../home" "/")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2027 @result{} "/../home"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2028 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2029 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2030
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2031 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2032 This is for the sake of filesystems that have the concept of a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2033 ``superroot'' above the root directory @file{/}. On other filesystems,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2034 @file{/../} is interpreted exactly the same as @file{/}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2035
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2036 Note that @code{expand-file-name} does @emph{not} expand environment
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2037 variables; only @code{substitute-in-file-name} does that.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2038
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2039 Note also that @code{expand-file-name} does not follow symbolic links
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2040 at any level. This results in a difference between the way
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2041 @code{file-truename} and @code{expand-file-name} treat @samp{..}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2042 Assuming that @samp{/tmp/bar} is a symbolic link to the directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2043 @samp{/tmp/foo/bar} we get:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2044
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2045 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2046 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2047 (file-truename "/tmp/bar/../myfile")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2048 @result{} "/tmp/foo/myfile"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2049 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2050 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2051 (expand-file-name "/tmp/bar/../myfile")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2052 @result{} "/tmp/myfile"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2053 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2054 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2055
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2056 If you may need to follow symbolic links preceding @samp{..}, you
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2057 should make sure to call @code{file-truename} without prior direct or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2058 indirect calls to @code{expand-file-name}. @xref{Truenames}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2059 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2060
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2061 @defvar default-directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2062 The value of this buffer-local variable is the default directory for the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2063 current buffer. It should be an absolute directory name; it may start
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2064 with @samp{~}. This variable is buffer-local in every buffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2065
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2066 @code{expand-file-name} uses the default directory when its second
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2067 argument is @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2068
97142
c3512b2085a0 * bitmaps/README:
Dan Nicolaescu <dann@ics.uci.edu>
parents: 91551
diff changeset
2069 The value is always a string ending with a slash.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2070
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2071 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2072 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2073 default-directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2074 @result{} "/user/lewis/manual/"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2075 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2076 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2077 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2078
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2079 @defun substitute-in-file-name filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2080 @anchor{Definition of substitute-in-file-name}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2081 This function replaces environment variable references in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2082 @var{filename} with the environment variable values. Following
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2083 standard Unix shell syntax, @samp{$} is the prefix to substitute an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2084 environment variable value. If the input contains @samp{$$}, that is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2085 converted to @samp{$}; this gives the user a way to ``quote'' a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2086 @samp{$}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2087
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2088 The environment variable name is the series of alphanumeric characters
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2089 (including underscores) that follow the @samp{$}. If the character following
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2090 the @samp{$} is a @samp{@{}, then the variable name is everything up to the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2091 matching @samp{@}}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2092
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2093 Calling @code{substitute-in-file-name} on output produced by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2094 @code{substitute-in-file-name} tends to give incorrect results. For
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2095 instance, use of @samp{$$} to quote a single @samp{$} won't work
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2096 properly, and @samp{$} in an environment variable's value could lead
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2097 to repeated substitution. Therefore, programs that call this function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2098 and put the output where it will be passed to this function need to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2099 double all @samp{$} characters to prevent subsequent incorrect
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2100 results.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2101
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2102 @c Wordy to avoid overfull hbox. --rjc 15mar92
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2103 Here we assume that the environment variable @code{HOME}, which holds
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2104 the user's home directory name, has value @samp{/xcssun/users/rms}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2105
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2106 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2107 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2108 (substitute-in-file-name "$HOME/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2109 @result{} "/xcssun/users/rms/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2110 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2111 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2112
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2113 After substitution, if a @samp{~} or a @samp{/} appears immediately
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2114 after another @samp{/}, the function discards everything before it (up
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2115 through the immediately preceding @samp{/}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2116
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2117 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2118 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2119 (substitute-in-file-name "bar/~/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2120 @result{} "~/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2121 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2122 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2123 (substitute-in-file-name "/usr/local/$HOME/foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2124 @result{} "/xcssun/users/rms/foo"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2125 ;; @r{@file{/usr/local/} has been discarded.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2126 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2127 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2128
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2129 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2130
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2131 @node Unique File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2132 @subsection Generating Unique File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2133
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2134 Some programs need to write temporary files. Here is the usual way to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2135 construct a name for such a file:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2136
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2137 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2138 (make-temp-file @var{name-of-application})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2139 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2140
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2141 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2142 The job of @code{make-temp-file} is to prevent two different users or
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2143 two different jobs from trying to use the exact same file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2144
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2145 @defun make-temp-file prefix &optional dir-flag suffix
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2146 This function creates a temporary file and returns its name. Emacs
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2147 creates the temporary file's name by adding to @var{prefix} some
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2148 random characters that are different in each Emacs job. The result is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2149 guaranteed to be a newly created empty file. On MS-DOS, this function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2150 can truncate the @var{string} prefix to fit into the 8+3 file-name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2151 limits. If @var{prefix} is a relative file name, it is expanded
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2152 against @code{temporary-file-directory}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2153
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2154 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2155 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2156 (make-temp-file "foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2157 @result{} "/tmp/foo232J6v"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2158 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2159 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2160
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2161 When @code{make-temp-file} returns, the file has been created and is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2162 empty. At that point, you should write the intended contents into the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2163 file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2164
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2165 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2166 empty directory instead of an empty file. It returns the file name,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2167 not the directory name, of that directory. @xref{Directory Names}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2168
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2169 If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2170 the end of the file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2171
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2172 To prevent conflicts among different libraries running in the same
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2173 Emacs, each Lisp program that uses @code{make-temp-file} should have its
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2174 own @var{prefix}. The number added to the end of @var{prefix}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2175 distinguishes between the same application running in different Emacs
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2176 jobs. Additional added characters permit a large number of distinct
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2177 names even in one Emacs job.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2178 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2179
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2180 The default directory for temporary files is controlled by the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2181 variable @code{temporary-file-directory}. This variable gives the user
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2182 a uniform way to specify the directory for all temporary files. Some
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2183 programs use @code{small-temporary-file-directory} instead, if that is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2184 non-@code{nil}. To use it, you should expand the prefix against
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2185 the proper directory before calling @code{make-temp-file}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2186
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2187 In older Emacs versions where @code{make-temp-file} does not exist,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2188 you should use @code{make-temp-name} instead:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2189
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2190 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2191 (make-temp-name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2192 (expand-file-name @var{name-of-application}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2193 temporary-file-directory))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2194 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2195
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2196 @defun make-temp-name string
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2197 This function generates a string that can be used as a unique file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2198 name. The name starts with @var{string}, and has several random
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2199 characters appended to it, which are different in each Emacs job. It
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2200 is like @code{make-temp-file} except that it just constructs a name,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2201 and does not create a file. Another difference is that @var{string}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2202 should be an absolute file name. On MS-DOS, this function can
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2203 truncate the @var{string} prefix to fit into the 8+3 file-name limits.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2204 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2205
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103264
diff changeset
2206 @defopt temporary-file-directory
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2207 @cindex @code{TMPDIR} environment variable
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2208 @cindex @code{TMP} environment variable
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2209 @cindex @code{TEMP} environment variable
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2210 This variable specifies the directory name for creating temporary files.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2211 Its value should be a directory name (@pxref{Directory Names}), but it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2212 is good for Lisp programs to cope if the value is a directory's file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2213 name instead. Using the value as the second argument to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2214 @code{expand-file-name} is a good way to achieve that.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2215
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2216 The default value is determined in a reasonable way for your operating
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2217 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2218 environment variables, with a fall-back to a system-dependent name if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2219 none of these variables is defined.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2220
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2221 Even if you do not use @code{make-temp-file} to create the temporary
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2222 file, you should still use this variable to decide which directory to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2223 put the file in. However, if you expect the file to be small, you
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2224 should use @code{small-temporary-file-directory} first if that is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2225 non-@code{nil}.
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103264
diff changeset
2226 @end defopt
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103264
diff changeset
2227
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103264
diff changeset
2228 @defopt small-temporary-file-directory
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2229 This variable specifies the directory name for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2230 creating certain temporary files, which are likely to be small.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2231
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2232 If you want to write a temporary file which is likely to be small, you
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2233 should compute the directory like this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2234
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2235 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2236 (make-temp-file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2237 (expand-file-name @var{prefix}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2238 (or small-temporary-file-directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2239 temporary-file-directory)))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2240 @end example
103273
c32ec20d0ab5 * abbrevs.texi (Abbrev Mode): abbrev-mode is an option.
Martin Rudalics <rudalics@gmx.at>
parents: 103264
diff changeset
2241 @end defopt
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2242
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2243 @node File Name Completion
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2244 @subsection File Name Completion
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2245 @cindex file name completion subroutines
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2246 @cindex completion, file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2247
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2248 This section describes low-level subroutines for completing a file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2249 name. For higher level functions, see @ref{Reading File Names}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2250
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2251 @defun file-name-all-completions partial-filename directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2252 This function returns a list of all possible completions for a file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2253 whose name starts with @var{partial-filename} in directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2254 @var{directory}. The order of the completions is the order of the files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2255 in the directory, which is unpredictable and conveys no useful
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2256 information.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2257
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2258 The argument @var{partial-filename} must be a file name containing no
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2259 directory part and no slash (or backslash on some systems). The current
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2260 buffer's default directory is prepended to @var{directory}, if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2261 @var{directory} is not absolute.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2262
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2263 In the following example, suppose that @file{~rms/lewis} is the current
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2264 default directory, and has five files whose names begin with @samp{f}:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2265 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2266 @file{file.c.~2~}.@refill
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2267
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2268 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2269 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2270 (file-name-all-completions "f" "")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2271 @result{} ("foo" "file~" "file.c.~2~"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2272 "file.c.~1~" "file.c")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2273 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2274
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2275 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2276 (file-name-all-completions "fo" "")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2277 @result{} ("foo")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2278 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2279 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2280 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2281
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2282 @defun file-name-completion filename directory &optional predicate
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2283 This function completes the file name @var{filename} in directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2284 @var{directory}. It returns the longest prefix common to all file names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2285 in directory @var{directory} that start with @var{filename}. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2286 @var{predicate} is non-@code{nil} then it ignores possible completions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2287 that don't satisfy @var{predicate}, after calling that function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2288 with one argument, the expanded absolute file name.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2289
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2290 If only one match exists and @var{filename} matches it exactly, the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2291 function returns @code{t}. The function returns @code{nil} if directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2292 @var{directory} contains no name starting with @var{filename}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2293
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2294 In the following example, suppose that the current default directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2295 has five files whose names begin with @samp{f}: @file{foo},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2296 @file{file~}, @file{file.c}, @file{file.c.~1~}, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2297 @file{file.c.~2~}.@refill
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2298
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2299 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2300 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2301 (file-name-completion "fi" "")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2302 @result{} "file"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2303 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2304
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2305 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2306 (file-name-completion "file.c.~1" "")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2307 @result{} "file.c.~1~"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2308 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2309
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2310 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2311 (file-name-completion "file.c.~1~" "")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2312 @result{} t
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2313 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2314
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2315 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2316 (file-name-completion "file.c.~3" "")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2317 @result{} nil
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2318 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2319 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2320 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2321
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2322 @defopt completion-ignored-extensions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2323 @code{file-name-completion} usually ignores file names that end in any
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2324 string in this list. It does not ignore them when all the possible
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2325 completions end in one of these suffixes. This variable has no effect
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2326 on @code{file-name-all-completions}.@refill
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2327
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2328 A typical value might look like this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2329
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2330 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2331 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2332 completion-ignored-extensions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2333 @result{} (".o" ".elc" "~" ".dvi")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2334 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2335 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2336
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2337 If an element of @code{completion-ignored-extensions} ends in a slash
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2338 @samp{/}, it signals a directory. The elements which do @emph{not} end
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2339 in a slash will never match a directory; thus, the above value will not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2340 filter out a directory named @file{foo.elc}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2341 @end defopt
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2342
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2343 @node Standard File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2344 @subsection Standard File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2345
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2346 Most of the file names used in Lisp programs are entered by the user.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2347 But occasionally a Lisp program needs to specify a standard file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2348 for a particular use---typically, to hold customization information
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2349 about each user. For example, abbrev definitions are stored (by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2350 default) in the file @file{~/.abbrev_defs}; the @code{completion}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2351 package stores completions in the file @file{~/.completions}. These are
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2352 two of the many standard file names used by parts of Emacs for certain
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2353 purposes.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2354
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2355 Various operating systems have their own conventions for valid file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2356 names and for which file names to use for user profile data. A Lisp
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2357 program which reads a file using a standard file name ought to use, on
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2358 each type of system, a file name suitable for that system. The function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2359 @code{convert-standard-filename} makes this easy to do.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2360
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2361 @defun convert-standard-filename filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2362 This function alters the file name @var{filename} to fit the conventions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2363 of the operating system in use, and returns the result as a new string.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2364 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2365
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2366 The recommended way to specify a standard file name in a Lisp program
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2367 is to choose a name which fits the conventions of GNU and Unix systems,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2368 usually with a nondirectory part that starts with a period, and pass it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2369 to @code{convert-standard-filename} instead of using it directly. Here
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2370 is an example from the @code{completion} package:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2371
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2372 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2373 (defvar save-completions-file-name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2374 (convert-standard-filename "~/.completions")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2375 "*The file name to save completions to.")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2376 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2377
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2378 On GNU and Unix systems, and on some other systems as well,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2379 @code{convert-standard-filename} returns its argument unchanged. On
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2380 some other systems, it alters the name to fit the system's conventions.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2381
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2382 For example, on MS-DOS the alterations made by this function include
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2383 converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2384 middle of the name to @samp{.} if there is no other @samp{.}, inserting
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2385 a @samp{.} after eight characters if there is none, and truncating to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2386 three characters after the @samp{.}. (It makes other changes as well.)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2387 Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2388 @file{.completions} becomes @file{_complet.ion}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2389
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2390 @node Contents of Directories
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2391 @section Contents of Directories
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2392 @cindex directory-oriented functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2393 @cindex file names in directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2394
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2395 A directory is a kind of file that contains other files entered under
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2396 various names. Directories are a feature of the file system.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2397
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2398 Emacs can list the names of the files in a directory as a Lisp list,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2399 or display the names in a buffer using the @code{ls} shell command. In
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2400 the latter case, it can optionally display information about each file,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2401 depending on the options passed to the @code{ls} command.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2402
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2403 @defun directory-files directory &optional full-name match-regexp nosort
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2404 This function returns a list of the names of the files in the directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2405 @var{directory}. By default, the list is in alphabetical order.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2406
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2407 If @var{full-name} is non-@code{nil}, the function returns the files'
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2408 absolute file names. Otherwise, it returns the names relative to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2409 the specified directory.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2410
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2411 If @var{match-regexp} is non-@code{nil}, this function returns only
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2412 those file names that contain a match for that regular expression---the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2413 other file names are excluded from the list. On case-insensitive
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2414 filesystems, the regular expression matching is case-insensitive.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2415
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2416 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2417 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2418 the list, so you get the file names in no particular order. Use this if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2419 you want the utmost possible speed and don't care what order the files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2420 are processed in. If the order of processing is visible to the user,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2421 then the user will probably be happier if you do sort the names.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2422
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2423 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2424 @group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2425 (directory-files "~lewis")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2426 @result{} ("#foo#" "#foo.el#" "." ".."
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2427 "dired-mods.el" "files.texi"
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2428 "files.texi.~1~")
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2429 @end group
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2430 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2431
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2432 An error is signaled if @var{directory} is not the name of a directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2433 that can be read.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2434 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2435
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2436 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2437 This is similar to @code{directory-files} in deciding which files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2438 to report on and how to report their names. However, instead
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2439 of returning a list of file names, it returns for each file a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2440 list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2441 is what @code{file-attributes} would return for that file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2442 The optional argument @var{id-format} has the same meaning as the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2443 corresponding argument to @code{file-attributes} (@pxref{Definition
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2444 of file-attributes}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2445 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2446
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2447 @defun file-expand-wildcards pattern &optional full
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2448 This function expands the wildcard pattern @var{pattern}, returning
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2449 a list of file names that match it.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2450
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2451 If @var{pattern} is written as an absolute file name,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2452 the values are absolute also.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2453
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2454 If @var{pattern} is written as a relative file name, it is interpreted
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2455 relative to the current default directory. The file names returned are
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2456 normally also relative to the current default directory. However, if
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2457 @var{full} is non-@code{nil}, they are absolute.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2458 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2459
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2460 @defun insert-directory file switches &optional wildcard full-directory-p
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2461 This function inserts (in the current buffer) a directory listing for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2462 directory @var{file}, formatted with @code{ls} according to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2463 @var{switches}. It leaves point after the inserted text.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2464 @var{switches} may be a string of options, or a list of strings
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2465 representing individual options.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2466
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2467 The argument @var{file} may be either a directory name or a file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2468 specification including wildcard characters. If @var{wildcard} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2469 non-@code{nil}, that means treat @var{file} as a file specification with
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2470 wildcards.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2471
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2472 If @var{full-directory-p} is non-@code{nil}, that means the directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2473 listing is expected to show the full contents of a directory. You
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2474 should specify @code{t} when @var{file} is a directory and switches do
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2475 not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2476 describe a directory itself as a file, rather than showing its
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2477 contents.)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2478
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2479 On most systems, this function works by running a directory listing
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2480 program whose name is in the variable @code{insert-directory-program}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2481 If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2482 @code{shell-file-name}, to expand the wildcards.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2483
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2484 MS-DOS and MS-Windows systems usually lack the standard Unix program
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2485 @code{ls}, so this function emulates the standard Unix program @code{ls}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2486 with Lisp code.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2487
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2488 As a technical detail, when @var{switches} contains the long
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2489 @samp{--dired} option, @code{insert-directory} treats it specially,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2490 for the sake of dired. However, the normally equivalent short
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2491 @samp{-D} option is just passed on to @code{insert-directory-program},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2492 as any other option.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2493 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2494
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2495 @defvar insert-directory-program
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2496 This variable's value is the program to run to generate a directory listing
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2497 for the function @code{insert-directory}. It is ignored on systems
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2498 which generate the listing with Lisp code.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2499 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2500
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2501 @node Create/Delete Dirs
105456
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2502 @section Creating, Copying and Deleting Directories
105460
7221464893e9 (File Attributes): Fix description of file attributes. (Bug#4638)
Eli Zaretskii <eliz@gnu.org>
parents: 105456
diff changeset
2503 @cindex creating, copying and deleting directories
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2504 @c Emacs 19 features
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2505
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2506 Most Emacs Lisp file-manipulation functions get errors when used on
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2507 files that are directories. For example, you cannot delete a directory
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2508 with @code{delete-file}. These special functions exist to create and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2509 delete directories.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2510
102832
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
2511 @findex mkdir
103264
b269cabac20c * syntax.texi (Position Parse): Document rationale for ignored
Chong Yidong <cyd@stupidchicken.com>
parents: 102832
diff changeset
2512 @deffn Command make-directory dirname &optional parents
b269cabac20c * syntax.texi (Position Parse): Document rationale for ignored
Chong Yidong <cyd@stupidchicken.com>
parents: 102832
diff changeset
2513 This command creates a directory named @var{dirname}. If
b269cabac20c * syntax.texi (Position Parse): Document rationale for ignored
Chong Yidong <cyd@stupidchicken.com>
parents: 102832
diff changeset
2514 @var{parents} is non-@code{nil}, as is always the case in an
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2515 interactive call, that means to create the parent directories first,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2516 if they don't already exist.
102832
9e5e877e0fd8 * files.texi (File Attributes): Move note about MS-DOS from
Chong Yidong <cyd@stupidchicken.com>
parents: 101344
diff changeset
2517
103264
b269cabac20c * syntax.texi (Position Parse): Document rationale for ignored
Chong Yidong <cyd@stupidchicken.com>
parents: 102832
diff changeset
2518 @code{mkdir} is an alias for this.
b269cabac20c * syntax.texi (Position Parse): Document rationale for ignored
Chong Yidong <cyd@stupidchicken.com>
parents: 102832
diff changeset
2519 @end deffn
b269cabac20c * syntax.texi (Position Parse): Document rationale for ignored
Chong Yidong <cyd@stupidchicken.com>
parents: 102832
diff changeset
2520
105456
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2521 @deffn Command copy-directory dirname newname &optional keep-time parents
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2522 This command copies the directory named @var{dirname} to
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2523 @var{newname}. If @var{newname} names an existing directory,
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2524 @var{dirname} will be copied to a subdirectory there.
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2525
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2526 It always sets the file modes of the copied files to match the
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2527 corresponding original file.
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2528
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2529 The third arg @var{keep-time} non-@code{nil} means to preserve the
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2530 modification time of the copied files. A prefix arg makes
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2531 @var{keep-time} non-@code{nil}.
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2532
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2533 Noninteractively, the last argument @var{parents} says whether to
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2534 create parent directories if they don't exist. Interactively,
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2535 this happens by default.
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2536 @end deffn
8b81962c202d * files.texi (Create/Delete Dirs): New command copy-directory.
Michael Albinus <michael.albinus@gmx.de>
parents: 105358
diff changeset
2537
105358
1510631c4c06 * files.texi (Directories): delete-directory has an optional
Michael Albinus <michael.albinus@gmx.de>
parents: 104571
diff changeset
2538 @deffn Command delete-directory dirname &optional recursive
103264
b269cabac20c * syntax.texi (Position Parse): Document rationale for ignored
Chong Yidong <cyd@stupidchicken.com>
parents: 102832
diff changeset
2539 This command deletes the directory named @var{dirname}. The function
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2540 @code{delete-file} does not work for files that are directories; you
105358
1510631c4c06 * files.texi (Directories): delete-directory has an optional
Michael Albinus <michael.albinus@gmx.de>
parents: 104571
diff changeset
2541 must use @code{delete-directory} for them. If @var{recursive} is
1510631c4c06 * files.texi (Directories): delete-directory has an optional
Michael Albinus <michael.albinus@gmx.de>
parents: 104571
diff changeset
2542 @code{nil}, and the directory contains any files,
1510631c4c06 * files.texi (Directories): delete-directory has an optional
Michael Albinus <michael.albinus@gmx.de>
parents: 104571
diff changeset
2543 @code{delete-directory} signals an error.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2544
103264
b269cabac20c * syntax.texi (Position Parse): Document rationale for ignored
Chong Yidong <cyd@stupidchicken.com>
parents: 102832
diff changeset
2545 @code{delete-directory} only follows symbolic links at the level of
b269cabac20c * syntax.texi (Position Parse): Document rationale for ignored
Chong Yidong <cyd@stupidchicken.com>
parents: 102832
diff changeset
2546 parent directories.
b269cabac20c * syntax.texi (Position Parse): Document rationale for ignored
Chong Yidong <cyd@stupidchicken.com>
parents: 102832
diff changeset
2547 @end deffn
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2548
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2549 @node Magic File Names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2550 @section Making Certain File Names ``Magic''
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2551 @cindex magic file names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2552
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2553 @c Emacs 19 feature
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2554 You can implement special handling for certain file names. This is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2555 called making those names @dfn{magic}. The principal use for this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2556 feature is in implementing remote file names (@pxref{Remote Files,,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2557 Remote Files, emacs, The GNU Emacs Manual}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2558
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2559 To define a kind of magic file name, you must supply a regular
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2560 expression to define the class of names (all those that match the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2561 regular expression), plus a handler that implements all the primitive
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2562 Emacs file operations for file names that do match.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2563
105639
c8da8bef4903 (Magic File Names): Add @vindex file-name-handler-alist,
Kevin Ryde <user42@zip.com.au>
parents: 105506
diff changeset
2564 @vindex file-name-handler-alist
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2565 The variable @code{file-name-handler-alist} holds a list of handlers,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2566 together with regular expressions that determine when to apply each
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2567 handler. Each element has this form:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2568
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2569 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2570 (@var{regexp} . @var{handler})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2571 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2572
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2573 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2574 All the Emacs primitives for file access and file name transformation
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2575 check the given file name against @code{file-name-handler-alist}. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2576 the file name matches @var{regexp}, the primitives handle that file by
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2577 calling @var{handler}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2578
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2579 The first argument given to @var{handler} is the name of the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2580 primitive, as a symbol; the remaining arguments are the arguments that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2581 were passed to that primitive. (The first of these arguments is most
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2582 often the file name itself.) For example, if you do this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2583
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2584 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2585 (file-exists-p @var{filename})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2586 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2587
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2588 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2589 and @var{filename} has handler @var{handler}, then @var{handler} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2590 called like this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2591
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2592 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2593 (funcall @var{handler} 'file-exists-p @var{filename})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2594 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2595
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2596 When a function takes two or more arguments that must be file names,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2597 it checks each of those names for a handler. For example, if you do
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2598 this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2599
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2600 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2601 (expand-file-name @var{filename} @var{dirname})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2602 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2603
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2604 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2605 then it checks for a handler for @var{filename} and then for a handler
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2606 for @var{dirname}. In either case, the @var{handler} is called like
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2607 this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2608
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2609 @example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2610 (funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2611 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2612
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2613 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2614 The @var{handler} then needs to figure out whether to handle
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2615 @var{filename} or @var{dirname}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2616
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2617 If the specified file name matches more than one handler, the one
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2618 whose match starts last in the file name gets precedence. This rule
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2619 is chosen so that handlers for jobs such as uncompression are handled
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2620 first, before handlers for jobs such as remote file access.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2621
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2622 Here are the operations that a magic file name handler gets to handle:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2623
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2624 @ifnottex
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2625 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2626 @code{access-file}, @code{add-name-to-file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2627 @code{byte-compiler-base-file-name},@*
105470
c575fd5ee9c2 * files.texi (Magic File Names): Add `copy-directory'.
Michael Albinus <michael.albinus@gmx.de>
parents: 105460
diff changeset
2628 @code{copy-directory}, @code{copy-file},
c575fd5ee9c2 * files.texi (Magic File Names): Add `copy-directory'.
Michael Albinus <michael.albinus@gmx.de>
parents: 105460
diff changeset
2629 @code{delete-directory}, @code{delete-file},
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2630 @code{diff-latest-backup-file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2631 @code{directory-file-name},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2632 @code{directory-files},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2633 @code{directory-files-and-attributes},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2634 @code{dired-compress-file}, @code{dired-uncache},@*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2635 @code{expand-file-name},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2636 @code{file-accessible-directory-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2637 @code{file-attributes},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2638 @code{file-directory-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2639 @code{file-executable-p}, @code{file-exists-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2640 @code{file-local-copy}, @code{file-remote-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2641 @code{file-modes}, @code{file-name-all-completions},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2642 @code{file-name-as-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2643 @code{file-name-completion},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2644 @code{file-name-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2645 @code{file-name-nondirectory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2646 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2647 @code{file-ownership-preserved-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2648 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2649 @code{file-truename}, @code{file-writable-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2650 @code{find-backup-file-name},
99477
0fd411ceb682 Remove find-file-noselect from the list of magic file name handlers.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 98927
diff changeset
2651 @c Not sure why it was here: @code{find-file-noselect},@*
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2652 @code{get-file-buffer},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2653 @code{insert-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2654 @code{insert-file-contents},@*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2655 @code{load},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2656 @code{make-auto-save-file-name},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2657 @code{make-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2658 @code{make-directory-internal},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2659 @code{make-symbolic-link},@*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2660 @code{process-file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2661 @code{rename-file}, @code{set-file-modes}, @code{set-file-times},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2662 @code{set-visited-file-modtime}, @code{shell-command},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2663 @code{start-file-process},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2664 @code{substitute-in-file-name},@*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2665 @code{unhandled-file-name-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2666 @code{vc-registered},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2667 @code{verify-visited-file-modtime},@*
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2668 @code{write-region}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2669 @end ifnottex
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2670 @iftex
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2671 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2672 @flushleft
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2673 @code{access-file}, @code{add-name-to-file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2674 @code{byte-com@discretionary{}{}{}piler-base-file-name},
105470
c575fd5ee9c2 * files.texi (Magic File Names): Add `copy-directory'.
Michael Albinus <michael.albinus@gmx.de>
parents: 105460
diff changeset
2675 @code{copy-directory}, @code{copy-file},
c575fd5ee9c2 * files.texi (Magic File Names): Add `copy-directory'.
Michael Albinus <michael.albinus@gmx.de>
parents: 105460
diff changeset
2676 @code{delete-directory}, @code{delete-file},
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2677 @code{diff-latest-backup-file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2678 @code{directory-file-name},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2679 @code{directory-files},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2680 @code{directory-files-and-at@discretionary{}{}{}tributes},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2681 @code{dired-compress-file}, @code{dired-uncache},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2682 @code{expand-file-name},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2683 @code{file-accessible-direc@discretionary{}{}{}tory-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2684 @code{file-attributes},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2685 @code{file-direct@discretionary{}{}{}ory-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2686 @code{file-executable-p}, @code{file-exists-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2687 @code{file-local-copy}, @code{file-remote-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2688 @code{file-modes}, @code{file-name-all-completions},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2689 @code{file-name-as-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2690 @code{file-name-completion},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2691 @code{file-name-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2692 @code{file-name-nondirec@discretionary{}{}{}tory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2693 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2694 @code{file-ownership-pre@discretionary{}{}{}served-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2695 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2696 @code{file-truename}, @code{file-writable-p},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2697 @code{find-backup-file-name},
99477
0fd411ceb682 Remove find-file-noselect from the list of magic file name handlers.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 98927
diff changeset
2698 @c Not sure why it was here: @code{find-file-noselect},
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2699 @code{get-file-buffer},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2700 @code{insert-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2701 @code{insert-file-contents},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2702 @code{load}, @code{make-direc@discretionary{}{}{}tory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2703 @code{make-direc@discretionary{}{}{}tory-internal},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2704 @code{make-symbolic-link},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2705 @code{process-file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2706 @code{rename-file}, @code{set-file-modes},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2707 @code{set-visited-file-modtime}, @code{shell-command},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2708 @code{start-file-process},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2709 @code{substitute-in-file-name},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2710 @code{unhandled-file-name-directory},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2711 @code{vc-regis@discretionary{}{}{}tered},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2712 @code{verify-visited-file-modtime},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2713 @code{write-region}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2714 @end flushleft
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2715 @end iftex
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2716
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2717 Handlers for @code{insert-file-contents} typically need to clear the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2718 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2719 @var{visit} argument is non-@code{nil}. This also has the effect of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2720 unlocking the buffer if it is locked.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2721
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2722 The handler function must handle all of the above operations, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2723 possibly others to be added in the future. It need not implement all
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2724 these operations itself---when it has nothing special to do for a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2725 certain operation, it can reinvoke the primitive, to handle the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2726 operation ``in the usual way.'' It should always reinvoke the primitive
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2727 for an operation it does not recognize. Here's one way to do this:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2728
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2729 @smallexample
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2730 (defun my-file-handler (operation &rest args)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2731 ;; @r{First check for the specific operations}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2732 ;; @r{that we have special handling for.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2733 (cond ((eq operation 'insert-file-contents) @dots{})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2734 ((eq operation 'write-region) @dots{})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2735 @dots{}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2736 ;; @r{Handle any operation we don't know about.}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2737 (t (let ((inhibit-file-name-handlers
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2738 (cons 'my-file-handler
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2739 (and (eq inhibit-file-name-operation operation)
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2740 inhibit-file-name-handlers)))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2741 (inhibit-file-name-operation operation))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2742 (apply operation args)))))
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2743 @end smallexample
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2744
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2745 When a handler function decides to call the ordinary Emacs primitive for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2746 the operation at hand, it needs to prevent the primitive from calling
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2747 the same handler once again, thus leading to an infinite recursion. The
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2748 example above shows how to do this, with the variables
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2749 @code{inhibit-file-name-handlers} and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2750 @code{inhibit-file-name-operation}. Be careful to use them exactly as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2751 shown above; the details are crucial for proper behavior in the case of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2752 multiple handlers, and for operations that have two file names that may
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2753 each have handlers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2754
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2755 @kindex safe-magic (@r{property})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2756 Handlers that don't really do anything special for actual access to the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2757 file---such as the ones that implement completion of host names for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2758 remote file names---should have a non-@code{nil} @code{safe-magic}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2759 property. For instance, Emacs normally ``protects'' directory names
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2760 it finds in @code{PATH} from becoming magic, if they look like magic
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2761 file names, by prefixing them with @samp{/:}. But if the handler that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2762 would be used for them has a non-@code{nil} @code{safe-magic}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2763 property, the @samp{/:} is not added.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2764
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2765 @kindex operations (@r{property})
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2766 A file name handler can have an @code{operations} property to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2767 declare which operations it handles in a nontrivial way. If this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2768 property has a non-@code{nil} value, it should be a list of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2769 operations; then only those operations will call the handler. This
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2770 avoids inefficiency, but its main purpose is for autoloaded handler
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2771 functions, so that they won't be loaded except when they have real
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2772 work to do.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2773
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2774 Simply deferring all operations to the usual primitives does not
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2775 work. For instance, if the file name handler applies to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2776 @code{file-exists-p}, then it must handle @code{load} itself, because
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2777 the usual @code{load} code won't work properly in that case. However,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2778 if the handler uses the @code{operations} property to say it doesn't
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2779 handle @code{file-exists-p}, then it need not handle @code{load}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2780 nontrivially.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2781
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2782 @defvar inhibit-file-name-handlers
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2783 This variable holds a list of handlers whose use is presently inhibited
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2784 for a certain operation.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2785 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2786
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2787 @defvar inhibit-file-name-operation
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2788 The operation for which certain handlers are presently inhibited.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2789 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2790
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2791 @defun find-file-name-handler file operation
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2792 This function returns the handler function for file name @var{file},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2793 or @code{nil} if there is none. The argument @var{operation} should
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2794 be the operation to be performed on the file---the value you will pass
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2795 to the handler as its first argument when you call it. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2796 @var{operation} equals @code{inhibit-file-name-operation}, or if it is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2797 not found in the @code{operations} property of the handler, this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2798 function returns @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2799 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2800
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2801 @defun file-local-copy filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2802 This function copies file @var{filename} to an ordinary non-magic file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2803 on the local machine, if it isn't on the local machine already. Magic
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2804 file names should handle the @code{file-local-copy} operation if they
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2805 refer to files on other machines. A magic file name that is used for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2806 other purposes than remote file access should not handle
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2807 @code{file-local-copy}; then this function will treat the file as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2808 local.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2809
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2810 If @var{filename} is local, whether magic or not, this function does
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2811 nothing and returns @code{nil}. Otherwise it returns the file name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2812 of the local copy file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2813 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2814
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2815 @defun file-remote-p filename &optional identification connected
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2816 This function tests whether @var{filename} is a remote file. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2817 @var{filename} is local (not remote), the return value is @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2818 If @var{filename} is indeed remote, the return value is a string that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2819 identifies the remote system.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2820
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2821 This identifier string can include a host name and a user name, as
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2822 well as characters designating the method used to access the remote
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2823 system. For example, the remote identifier string for the filename
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2824 @code{/sudo::/some/file} is @code{/sudo:root@@localhost:}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2825
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2826 If @code{file-remote-p} returns the same identifier for two different
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2827 filenames, that means they are stored on the same file system and can
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2828 be accessed locally with respect to each other. This means, for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2829 example, that it is possible to start a remote process accessing both
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2830 files at the same time. Implementors of file handlers need to ensure
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2831 this principle is valid.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2832
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2833 @var{identification} specifies which part of the identifier shall be
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2834 returned as string. @var{identification} can be the symbol
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2835 @code{method}, @code{user} or @code{host}; any other value is handled
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2836 like @code{nil} and means to return the complete identifier string.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2837 In the example above, the remote @code{user} identifier string would
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2838 be @code{root}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2839
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2840 If @var{connected} is non-@code{nil}, this function returns @code{nil}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2841 even if @var{filename} is remote, if Emacs has no network connection
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2842 to its host. This is useful when you want to avoid the delay of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2843 making connections when they don't exist.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2844 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2845
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2846 @defun unhandled-file-name-directory filename
99912
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
2847 This function returns the name of a directory that is not magic. It
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
2848 uses the directory part of @var{filename} if that is not magic. For a
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
2849 magic file name, it invokes the file name handler, which therefore
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
2850 decides what value to return. If @var{filename} is not accessible
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
2851 from a local process, then the file name handler should indicate it by
b745b2161485 (Changing Files, Magic File Names): Fix typos.
Chong Yidong <cyd@stupidchicken.com>
parents: 99733
diff changeset
2852 returning @code{nil}.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2853
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2854 This is useful for running a subprocess; every subprocess must have a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2855 non-magic directory to serve as its current directory, and this function
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2856 is a good way to come up with one.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2857 @end defun
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2858
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2859 @node Format Conversion
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2860 @section File Format Conversion
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2861
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2862 @cindex file format conversion
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2863 @cindex encoding file formats
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2864 @cindex decoding file formats
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2865 @cindex text properties in files
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2866 @cindex saving text properties
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2867 Emacs performs several steps to convert the data in a buffer (text,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2868 text properties, and possibly other information) to and from a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2869 representation suitable for storing into a file. This section describes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2870 the fundamental functions that perform this @dfn{format conversion},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2871 namely @code{insert-file-contents} for reading a file into a buffer,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2872 and @code{write-region} for writing a buffer into a file.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2873
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2874 @menu
103829
0883932a218b (Format Conversion): End menu description with period.
Glenn Morris <rgm@gnu.org>
parents: 103273
diff changeset
2875 * Overview: Format Conversion Overview. @code{insert-file-contents} and @code{write-region}.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2876 * Round-Trip: Format Conversion Round-Trip. Using @code{format-alist}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2877 * Piecemeal: Format Conversion Piecemeal. Specifying non-paired conversion.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2878 @end menu
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2879
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2880 @node Format Conversion Overview
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2881 @subsection Overview
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2882 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2883 The function @code{insert-file-contents}:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2884
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2885 @itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2886 @item initially, inserts bytes from the file into the buffer;
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2887 @item decodes bytes to characters as appropriate;
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2888 @item processes formats as defined by entries in @code{format-alist}; and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2889 @item calls functions in @code{after-insert-file-functions}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2890 @end itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2891
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2892 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2893 The function @code{write-region}:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2894
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2895 @itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2896 @item initially, calls functions in @code{write-region-annotate-functions};
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2897 @item processes formats as defined by entries in @code{format-alist};
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2898 @item encodes characters to bytes as appropriate; and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2899 @item modifies the file with the bytes.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2900 @end itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2901
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2902 This shows the symmetry of the lowest-level operations; reading and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2903 writing handle things in opposite order. The rest of this section
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2904 describes the two facilities surrounding the three variables named
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2905 above, as well as some related functions. @ref{Coding Systems}, for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2906 details on character encoding and decoding.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2907
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2908 @node Format Conversion Round-Trip
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2909 @subsection Round-Trip Specification
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2910
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2911 The most general of the two facilities is controlled by the variable
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2912 @code{format-alist}, a list of @dfn{file format} specifications, which
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2913 describe textual representations used in files for the data in an Emacs
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2914 buffer. The descriptions for reading and writing are paired, which is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2915 why we call this ``round-trip'' specification
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2916 (@pxref{Format Conversion Piecemeal}, for non-paired specification).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2917
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2918 @defvar format-alist
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2919 This list contains one format definition for each defined file format.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2920 Each format definition is a list of this form:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2921
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2922 @example
99733
15f3f8c7992a (Format Conversion Round-Trip): Mention `preserve' element of `format-alist'.
Glenn Morris <rgm@gnu.org>
parents: 99526
diff changeset
2923 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn} @var{preserve})
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2924 @end example
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2925 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2926
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2927 @cindex format definition
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2928 @noindent
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2929 Here is what the elements in a format definition mean:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2930
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2931 @table @var
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2932 @item name
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2933 The name of this format.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2934
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2935 @item doc-string
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2936 A documentation string for the format.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2937
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2938 @item regexp
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2939 A regular expression which is used to recognize files represented in
104571
904d63cfa2f3 (Format Conversion Round-Trip): Mention nil regexp.
Glenn Morris <rgm@gnu.org>
parents: 103829
diff changeset
2940 this format. If @code{nil}, the format is never applied automatically.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2941
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2942 @item from-fn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2943 A shell command or function to decode data in this format (to convert
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2944 file data into the usual Emacs data representation).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2945
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2946 A shell command is represented as a string; Emacs runs the command as a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2947 filter to perform the conversion.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2948
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2949 If @var{from-fn} is a function, it is called with two arguments, @var{begin}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2950 and @var{end}, which specify the part of the buffer it should convert.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2951 It should convert the text by editing it in place. Since this can
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2952 change the length of the text, @var{from-fn} should return the modified
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2953 end position.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2954
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2955 One responsibility of @var{from-fn} is to make sure that the beginning
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2956 of the file no longer matches @var{regexp}. Otherwise it is likely to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2957 get called again.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2958
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2959 @item to-fn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2960 A shell command or function to encode data in this format---that is, to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2961 convert the usual Emacs data representation into this format.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2962
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2963 If @var{to-fn} is a string, it is a shell command; Emacs runs the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2964 command as a filter to perform the conversion.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2965
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2966 If @var{to-fn} is a function, it is called with three arguments:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2967 @var{begin} and @var{end}, which specify the part of the buffer it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2968 should convert, and @var{buffer}, which specifies which buffer. There
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2969 are two ways it can do the conversion:
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2970
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2971 @itemize @bullet
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2972 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2973 By editing the buffer in place. In this case, @var{to-fn} should
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2974 return the end-position of the range of text, as modified.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2975
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2976 @item
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2977 By returning a list of annotations. This is a list of elements of the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2978 form @code{(@var{position} . @var{string})}, where @var{position} is an
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2979 integer specifying the relative position in the text to be written, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2980 @var{string} is the annotation to add there. The list must be sorted in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2981 order of position when @var{to-fn} returns it.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2982
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2983 When @code{write-region} actually writes the text from the buffer to the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2984 file, it intermixes the specified annotations at the corresponding
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2985 positions. All this takes place without modifying the buffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2986 @end itemize
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2987
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2988 @item modify
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2989 A flag, @code{t} if the encoding function modifies the buffer, and
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2990 @code{nil} if it works by returning a list of annotations.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2991
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2992 @item mode-fn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2993 A minor-mode function to call after visiting a file converted from this
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2994 format. The function is called with one argument, the integer 1;
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
2995 that tells a minor-mode function to enable the mode.
99733
15f3f8c7992a (Format Conversion Round-Trip): Mention `preserve' element of `format-alist'.
Glenn Morris <rgm@gnu.org>
parents: 99526
diff changeset
2996
15f3f8c7992a (Format Conversion Round-Trip): Mention `preserve' element of `format-alist'.
Glenn Morris <rgm@gnu.org>
parents: 99526
diff changeset
2997 @item preserve
15f3f8c7992a (Format Conversion Round-Trip): Mention `preserve' element of `format-alist'.
Glenn Morris <rgm@gnu.org>
parents: 99526
diff changeset
2998 A flag, @code{t} if @code{format-write-file} should not remove this format
15f3f8c7992a (Format Conversion Round-Trip): Mention `preserve' element of `format-alist'.
Glenn Morris <rgm@gnu.org>
parents: 99526
diff changeset
2999 from @code{buffer-file-format}.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3000 @end table
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3001
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3002 The function @code{insert-file-contents} automatically recognizes file
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3003 formats when it reads the specified file. It checks the text of the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3004 beginning of the file against the regular expressions of the format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3005 definitions, and if it finds a match, it calls the decoding function for
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3006 that format. Then it checks all the known formats over again.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3007 It keeps checking them until none of them is applicable.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3008
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3009 Visiting a file, with @code{find-file-noselect} or the commands that use
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3010 it, performs conversion likewise (because it calls
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3011 @code{insert-file-contents}); it also calls the mode function for each
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3012 format that it decodes. It stores a list of the format names in the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3013 buffer-local variable @code{buffer-file-format}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3014
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3015 @defvar buffer-file-format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3016 This variable states the format of the visited file. More precisely,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3017 this is a list of the file format names that were decoded in the course
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3018 of visiting the current buffer's file. It is always buffer-local in all
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3019 buffers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3020 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3021
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3022 When @code{write-region} writes data into a file, it first calls the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3023 encoding functions for the formats listed in @code{buffer-file-format},
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3024 in the order of appearance in the list.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3025
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3026 @deffn Command format-write-file file format &optional confirm
100115
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
3027 This command writes the current buffer contents into the file @var{file}
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
3028 in a format based on @var{format}, which is a list of format names. It
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
3029 constructs the actual format starting from @var{format}, then appending
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
3030 any elements from the value of @code{buffer-file-format} with a non-nil
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
3031 @var{preserve} flag (see above), if they are not already present in
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
3032 @var{format}. It then updates @code{buffer-file-format} with this
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
3033 format, making it the default for future saves. Except for the
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
3034 @var{format} argument, this command is similar to @code{write-file}. In
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
3035 particular, @var{confirm} has the same meaning and interactive treatment
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
3036 as the corresponding argument to @code{write-file}. @xref{Definition of
3a36c6c70cad (Format Conversion Round-Trip): Rewrite format-write-file section yet again.
Glenn Morris <rgm@gnu.org>
parents: 99999
diff changeset
3037 write-file}.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3038 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3039
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3040 @deffn Command format-find-file file format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3041 This command finds the file @var{file}, converting it according to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3042 format @var{format}. It also makes @var{format} the default if the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3043 buffer is saved later.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3044
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3045 The argument @var{format} is a list of format names. If @var{format} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3046 @code{nil}, no conversion takes place. Interactively, typing just
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3047 @key{RET} for @var{format} specifies @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3048 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3049
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3050 @deffn Command format-insert-file file format &optional beg end
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3051 This command inserts the contents of file @var{file}, converting it
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3052 according to format @var{format}. If @var{beg} and @var{end} are
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3053 non-@code{nil}, they specify which part of the file to read, as in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3054 @code{insert-file-contents} (@pxref{Reading from Files}).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3055
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3056 The return value is like what @code{insert-file-contents} returns: a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3057 list of the absolute file name and the length of the data inserted
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3058 (after conversion).
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3059
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3060 The argument @var{format} is a list of format names. If @var{format} is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3061 @code{nil}, no conversion takes place. Interactively, typing just
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3062 @key{RET} for @var{format} specifies @code{nil}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3063 @end deffn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3064
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3065 @defvar buffer-auto-save-file-format
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3066 This variable specifies the format to use for auto-saving. Its value is
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3067 a list of format names, just like the value of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3068 @code{buffer-file-format}; however, it is used instead of
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3069 @code{buffer-file-format} for writing auto-save files. If the value
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3070 is @code{t}, the default, auto-saving uses the same format as a
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3071 regular save in the same buffer. This variable is always buffer-local
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3072 in all buffers.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3073 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3074
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3075 @node Format Conversion Piecemeal
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3076 @subsection Piecemeal Specification
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3077
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3078 In contrast to the round-trip specification described in the previous
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3079 subsection (@pxref{Format Conversion Round-Trip}), you can use the variables
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3080 @code{after-insert-file-functions} and @code{write-region-annotate-functions}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3081 to separately control the respective reading and writing conversions.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3082
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3083 Conversion starts with one representation and produces another
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3084 representation. When there is only one conversion to do, there is no
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3085 conflict about what to start with. However, when there are multiple
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3086 conversions involved, conflict may arise when two conversions need to
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3087 start with the same data.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3088
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3089 This situation is best understood in the context of converting text
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3090 properties during @code{write-region}. For example, the character at
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3091 position 42 in a buffer is @samp{X} with a text property @code{foo}. If
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3092 the conversion for @code{foo} is done by inserting into the buffer, say,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3093 @samp{FOO:}, then that changes the character at position 42 from
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3094 @samp{X} to @samp{F}. The next conversion will start with the wrong
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3095 data straight away.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3096
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3097 To avoid conflict, cooperative conversions do not modify the buffer,
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3098 but instead specify @dfn{annotations}, a list of elements of the form
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3099 @code{(@var{position} . @var{string})}, sorted in order of increasing
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3100 @var{position}.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3101
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3102 If there is more than one conversion, @code{write-region} merges their
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3103 annotations destructively into one sorted list. Later, when the text
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3104 from the buffer is actually written to the file, it intermixes the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3105 specified annotations at the corresponding positions. All this takes
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3106 place without modifying the buffer.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3107
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3108 @c ??? What about ``overriding'' conversions like those allowed
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3109 @c ??? for `write-region-annotate-functions', below? --ttn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3110
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3111 In contrast, when reading, the annotations intermixed with the text
101344
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3112 are handled immediately. @code{insert-file-contents} sets point to
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3113 the beginning of some text to be converted, then calls the conversion
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3114 functions with the length of that text. These functions should always
101344
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3115 return with point at the beginning of the inserted text. This
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3116 approach makes sense for reading because annotations removed by the
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3117 first converter can't be mistakenly processed by a later converter.
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3118 Each conversion function should scan for the annotations it
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3119 recognizes, remove the annotation, modify the buffer text (to set a
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3120 text property, for example), and return the updated length of the
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3121 text, as it stands after those changes. The value returned by one
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3122 function becomes the argument to the next function.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3123
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3124 @defvar write-region-annotate-functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3125 A list of functions for @code{write-region} to call. Each function in
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3126 the list is called with two arguments: the start and end of the region
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3127 to be written. These functions should not alter the contents of the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3128 buffer. Instead, they should return annotations.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3129
101344
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3130 As a special case, a function may return with a different buffer
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3131 current. Emacs takes this to mean that the current buffer contains
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3132 altered text to be output. It therefore changes the @var{start} and
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3133 @var{end} arguments of the @code{write-region} call, giving them the
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3134 values of @code{point-min} and @code{point-max} in the new buffer,
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3135 respectively. It also discards all previous annotations, because they
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3136 should have been dealt with by this function.
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3137 @end defvar
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3138
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3139 @defvar write-region-post-annotation-function
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3140 The value of this variable, if non-@code{nil}, should be a function.
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3141 This function is called, with no arguments, after @code{write-region}
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3142 has completed.
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3143
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3144 If any function in @code{write-region-annotate-functions} returns with
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3145 a different buffer current, Emacs calls
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3146 @code{write-region-post-annotation-function} more than once. Emacs
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3147 calls it with the last buffer that was current, and again with the
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3148 buffer before that, and so on back to the original buffer.
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3149
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3150 Thus, a function in @code{write-region-annotate-functions} can create
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3151 a buffer, give this variable the local value of @code{kill-buffer} in
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3152 that buffer, set up the buffer with altered text, and make the buffer
50175350da19 (Format Conversion Piecemeal): Clarify behavior of
Chong Yidong <cyd@stupidchicken.com>
parents: 101050
diff changeset
3153 current. The buffer will be killed after @code{write-region} is done.
84067
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3154 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3155
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3156 @defvar after-insert-file-functions
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3157 Each function in this list is called by @code{insert-file-contents}
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3158 with one argument, the number of characters inserted, and with point
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3159 at the beginning of the inserted text. Each function should leave
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3160 point unchanged, and return the new character count describing the
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3161 inserted text as modified by the function.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3162 @c ??? The docstring mentions a handler from `file-name-handler-alist'
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3163 @c "intercepting" `insert-file-contents'. Hmmm. --ttn
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3164 @end defvar
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3165
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3166 We invite users to write Lisp programs to store and retrieve text
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3167 properties in files, using these hooks, and thus to experiment with
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3168 various data formats and find good ones. Eventually we hope users
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3169 will produce good, general extensions we can install in Emacs.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3170
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3171 We suggest not trying to handle arbitrary Lisp objects as text property
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3172 names or values---because a program that general is probably difficult
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3173 to write, and slow. Instead, choose a set of possible data types that
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3174 are reasonably flexible, and not too hard to encode.
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3175
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3176 @ignore
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3177 arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c
d39de40c9c66 Move here from ../../lispref
Glenn Morris <rgm@gnu.org>
parents:
diff changeset
3178 @end ignore