annotate lispref/files.texi @ 51667:52d50e52438f

(struct buffer_text): Lisp_Object `markers' => Lisp_Marker.
author Stefan Monnier <monnier@iro.umontreal.ca>
date Thu, 26 Jun 2003 23:15:25 +0000
parents 24b62b8f3def
children ccbf5ac3316d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
27189
d2e5f1b7d8e2 Update copyrights.
Gerd Moellmann <gerd@gnu.org>
parents: 27187
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
4 @c Free Software Foundation, Inc.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
7 @node Files, Backups and Auto-Saving, Documentation, Top
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @comment node-name, next, previous, up
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @chapter Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 In Emacs, you can find, create, view, save, and otherwise work with
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 files and file directories. This chapter describes most of the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 file-related functions of Emacs Lisp, but a few others are described in
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 @ref{Buffers}, and those related to backups and auto-saving are
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 described in @ref{Backups and Auto-Saving}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
17 Many of the file functions take one or more arguments that are file
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
18 names. A file name is actually a string. Most of these functions
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
19 expand file name arguments by calling @code{expand-file-name}, so that
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
20 @file{~} is handled correctly, as are relative file names (including
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
21 @samp{../}). These functions don't recognize environment variable
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
22 substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
23
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
24 When file I/O functions signal Lisp errors, they usually use the
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
25 condition @code{file-error} (@pxref{Handling Errors}). The error
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
26 message is in most cases obtained from the operating system, according
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
27 to locale @code{system-message-locale}, and decoded using coding system
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
28 @code{locale-coding-system} (@pxref{Locales}).
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
29
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
30 @menu
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
31 * Visiting Files:: Reading files into Emacs buffers for editing.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32 * Saving Buffers:: Writing changed buffers back into files.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33 * Reading from Files:: Reading files into buffers without visiting.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 * Writing to Files:: Writing new files from parts of buffers.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 * File Locks:: Locking and unlocking files, to prevent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36 simultaneous editing by two people.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 * Information about Files:: Testing existence, accessibility, size of files.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
38 * Changing Files:: Renaming files, changing protection, etc.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
39 * File Names:: Decomposing and expanding file names.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
40 * Contents of Directories:: Getting a list of the files in a directory.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
41 * Create/Delete Dirs:: Creating and Deleting Directories.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42 * Magic File Names:: Defining "magic" special handling
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
43 for certain file names.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
44 * Format Conversion:: Conversion to and from various file formats.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
45 @end menu
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
46
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 @node Visiting Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
48 @section Visiting Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 @cindex finding files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 @cindex visiting files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 Visiting a file means reading a file into a buffer. Once this is
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53 done, we say that the buffer is @dfn{visiting} that file, and call the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
54 file ``the visited file'' of the buffer.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 A file and a buffer are two different things. A file is information
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57 recorded permanently in the computer (unless you delete it). A buffer,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 on the other hand, is information inside of Emacs that will vanish at
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 the end of the editing session (or when you kill the buffer). Usually,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 a buffer contains information that you have copied from a file; then we
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 say the buffer is visiting that file. The copy in the buffer is what
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 you modify with editing commands. Such changes to the buffer do not
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 change the file; therefore, to make the changes permanent, you must
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64 @dfn{save} the buffer, which means copying the altered buffer contents
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 back into the file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 In spite of the distinction between files and buffers, people often
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
69 ``I am editing a file,'' rather than, ``I am editing a buffer that I
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 will soon save as a file of the same name.'' Humans do not usually need
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 to make the distinction explicit. When dealing with a computer program,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 however, it is good to keep the distinction in mind.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74 @menu
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
75 * Visiting Functions:: The usual interface functions for visiting.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 * Subroutines of Visiting:: Lower-level subroutines that they use.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 @end menu
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79 @node Visiting Functions
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 @subsection Functions for Visiting Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
81
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 This section describes the functions normally used to visit files.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 For historical reasons, these functions have names starting with
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 @samp{find-} rather than @samp{visit-}. @xref{Buffer File Name}, for
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 functions and variables that access the visited file name of a buffer or
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
86 that find an existing buffer by its visited file name.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
87
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
88 In a Lisp program, if you want to look at the contents of a file but
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
89 not alter it, the fastest way is to use @code{insert-file-contents} in a
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
90 temporary buffer. Visiting the file is not necessary and takes longer.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
91 @xref{Reading from Files}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
92
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
93 @deffn Command find-file filename &optional wildcards
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
94 This command selects a buffer visiting the file @var{filename},
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
95 using an existing buffer if there is one, and otherwise creating a
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
96 new buffer and reading the file into it. It also returns that buffer.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
97
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
98 The body of the @code{find-file} function is very simple and looks
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
99 like this:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 (switch-to-buffer (find-file-noselect filename))
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 (See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
108 If @var{wildcards} is non-@code{nil}, which is always true in an
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
109 interactive call, then @code{find-file} expands wildcard characters in
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
110 @var{filename} and visits all the matching files.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
111
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 When @code{find-file} is called interactively, it prompts for
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 @var{filename} in the minibuffer.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
116 @defun find-file-noselect filename &optional nowarn rawfile wildcards
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 This function is the guts of all the file-visiting functions. It finds
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 or creates a buffer visiting the file @var{filename}, and returns it.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 It uses an existing buffer if there is one, and otherwise creates a new
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 buffer and reads the file into it. You may make the buffer current or
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121 display it in a window if you wish, but this function does not do so.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122
24952
a6db4671c7a0 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24951
diff changeset
123 If @var{wildcards} is non-@code{nil},
a6db4671c7a0 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24951
diff changeset
124 then @code{find-file-noselect} expands wildcard
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
125 characters in @var{filename} and visits all the matching files.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
126
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 When @code{find-file-noselect} uses an existing buffer, it first
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 verifies that the file has not changed since it was last visited or
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 saved in that buffer. If the file has changed, then this function asks
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 the user whether to reread the changed file. If the user says
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @samp{yes}, any changes previously made in the buffer are lost.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
133 This function displays warning or advisory messages in various peculiar
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
134 cases, unless the optional argument @var{nowarn} is non-@code{nil}. For
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
135 example, if it needs to create a buffer, and there is no file named
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
136 @var{filename}, it displays the message @samp{(New file)} in the echo
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
137 area, and leaves the buffer empty.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
138
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
139 The @code{find-file-noselect} function normally calls
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
140 @code{after-find-file} after reading the file (@pxref{Subroutines of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
141 Visiting}). That function sets the buffer major mode, parses local
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
142 variables, warns the user if there exists an auto-save file more recent
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
143 than the file just visited, and finishes by running the functions in
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
144 @code{find-file-hook}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
145
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
146 If the optional argument @var{rawfile} is non-@code{nil}, then
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
147 @code{after-find-file} is not called, and the
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
148 @code{find-file-not-found-functions} are not run in case of failure. What's
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
149 more, a non-@code{nil} @var{rawfile} value suppresses coding system
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
150 conversion (@pxref{Coding Systems}) and format conversion (@pxref{Format
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
151 Conversion}).
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
152
32842
b10fc3a9befa (Visiting Functions): Return value of find-file-noselect may be a list
Kenichi Handa <handa@m17n.org>
parents: 30501
diff changeset
153 The @code{find-file-noselect} function usually returns the buffer that
b10fc3a9befa (Visiting Functions): Return value of find-file-noselect may be a list
Kenichi Handa <handa@m17n.org>
parents: 30501
diff changeset
154 is visiting the file @var{filename}. But, if wildcards are actually
32859
7600e7ac0dcd (Visiting Functions): Typos.
Gerd Moellmann <gerd@gnu.org>
parents: 32842
diff changeset
155 used and expanded, it returns a list of buffers that are visiting the
32842
b10fc3a9befa (Visiting Functions): Return value of find-file-noselect may be a list
Kenichi Handa <handa@m17n.org>
parents: 30501
diff changeset
156 various files.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 (find-file-noselect "/etc/fstab")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 @result{} #<buffer fstab>
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
166 @deffn Command find-file-other-window filename &optional wildcards
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167 This command selects a buffer visiting the file @var{filename}, but
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
168 does so in a window other than the selected window. It may use another
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 existing window or split a window; see @ref{Displaying Buffers}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
171 When this command is called interactively, it prompts for
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172 @var{filename}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
175 @deffn Command find-file-read-only filename &optional wildcards
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176 This command selects a buffer visiting the file @var{filename}, like
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
177 @code{find-file}, but it marks the buffer as read-only. @xref{Read Only
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 Buffers}, for related functions and variables.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
180 When this command is called interactively, it prompts for
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181 @var{filename}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 @deffn Command view-file filename
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
185 This command visits @var{filename} using View mode, returning to the
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
186 previous buffer when you exit View mode. View mode is a minor mode that
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
187 provides commands to skim rapidly through the file, but does not let you
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
188 modify the text. Entering View mode runs the normal hook
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
189 @code{view-mode-hook}. @xref{Hooks}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
190
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
191 When @code{view-file} is called interactively, it prompts for
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192 @var{filename}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
195 @tindex find-file-wildcards
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
196 @defvar find-file-wildcards
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
197 If this variable is non-@code{nil}, then the various @code{find-file}
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
198 commands check for wildcard characters and visit all the files that
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
199 match them. If this is @code{nil}, then wildcard characters are
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
200 not treated specially.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
201 @end defvar
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
202
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
203 @defvar find-file-hook
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
204 The value of this variable is a list of functions to be called after a
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
205 file is visited. The file's local-variables specification (if any) will
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
206 have been processed before the hooks are run. The buffer visiting the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207 file is current when the hook functions are run.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
208
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 This variable works just like a normal hook, but we think that renaming
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
210 it would not be advisable. @xref{Hooks}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211 @end defvar
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
213 @defvar find-file-not-found-functions
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 The value of this variable is a list of functions to be called when
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 @code{find-file} or @code{find-file-noselect} is passed a nonexistent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 file name. @code{find-file-noselect} calls these functions as soon as
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 it detects a nonexistent file. It calls them in the order of the list,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 until one of them returns non-@code{nil}. @code{buffer-file-name} is
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 already set up.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221 This is not a normal hook because the values of the functions are
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
222 used, and in many cases only some of the functions are called.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 @end defvar
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
224
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
225 @node Subroutines of Visiting
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226 @comment node-name, next, previous, up
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 @subsection Subroutines of Visiting
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
229 The @code{find-file-noselect} function uses two important subroutines
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
230 which are sometimes useful in user Lisp code: @code{create-file-buffer}
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
231 and @code{after-find-file}. This section explains how to use them.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 @defun create-file-buffer filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
234 This function creates a suitably named buffer for visiting
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 @var{filename}, and returns it. It uses @var{filename} (sans directory)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 as the name if that name is free; otherwise, it appends a string such as
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 @samp{<2>} to get an unused name. See also @ref{Creating Buffers}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 @strong{Please note:} @code{create-file-buffer} does @emph{not}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240 associate the new buffer with a file and does not select the buffer.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
241 It also does not use the default major mode.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
243 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 (create-file-buffer "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 @result{} #<buffer foo>
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 (create-file-buffer "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 @result{} #<buffer foo<2>>
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253 (create-file-buffer "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 @result{} #<buffer foo<3>>
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 This function is used by @code{find-file-noselect}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
262 @defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263 This function sets the buffer major mode, and parses local variables
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
264 (@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 and by the default revert function (@pxref{Reverting}).
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 @cindex new file message
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268 @cindex file open error
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 If reading the file got an error because the file does not exist, but
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 its directory does exist, the caller should pass a non-@code{nil} value
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 for @var{error}. In that case, @code{after-find-file} issues a warning:
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
272 @samp{(New file)}. For more serious errors, the caller should usually not
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
273 call @code{after-find-file}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
274
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
275 If @var{warn} is non-@code{nil}, then this function issues a warning
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276 if an auto-save file exists and is more recent than the visited file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
278 If @var{noauto} is non-@code{nil}, that says not to enable or disable
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
279 Auto-Save mode. The mode remains enabled if it was enabled before.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
280
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
281 If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
282 means this call was from @code{revert-buffer}. This has no direct
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
283 effect, but some mode functions and hook functions check the value
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
284 of this variable.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
285
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
286 If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
287 major mode, don't process local variables specifications in the file,
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
288 and don't run @code{find-file-hook}. This feature is used by
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
289 @code{revert-buffer} in some cases.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
290
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 The last thing @code{after-find-file} does is call all the functions
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
292 in the list @code{find-file-hook}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
294
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295 @node Saving Buffers
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296 @section Saving Buffers
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 When you edit a file in Emacs, you are actually working on a buffer
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
299 that is visiting that file---that is, the contents of the file are
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300 copied into the buffer and the copy is what you edit. Changes to the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 buffer do not change the file until you @dfn{save} the buffer, which
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
302 means copying the contents of the buffer into the file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
303
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
304 @deffn Command save-buffer &optional backup-option
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
305 This function saves the contents of the current buffer in its visited
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306 file if the buffer has been modified since it was last visited or saved.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 Otherwise it does nothing.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 @code{save-buffer} is responsible for making backup files. Normally,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
310 @var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
311 file only if this is the first save since visiting the file. Other
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
312 values for @var{backup-option} request the making of backup files in
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
313 other circumstances:
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
314
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
315 @itemize @bullet
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
316 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317 With an argument of 4 or 64, reflecting 1 or 3 @kbd{C-u}'s, the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 @code{save-buffer} function marks this version of the file to be
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 backed up when the buffer is next saved.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
321 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323 @code{save-buffer} function unconditionally backs up the previous
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 version of the file before saving it.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 @end itemize
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
326 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327
26770
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
328 @deffn Command save-some-buffers &optional save-silently-p pred
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 This command saves some modified file-visiting buffers. Normally it
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330 asks the user about each buffer. But if @var{save-silently-p} is
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 non-@code{nil}, it saves all the file-visiting buffers without querying
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 the user.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333
26770
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
334 The optional @var{pred} argument controls which buffers to ask about.
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
335 If it is @code{nil}, that means to ask only about file-visiting buffers.
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
336 If it is @code{t}, that means also offer to save certain other non-file
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
337 buffers---those that have a non-@code{nil} buffer-local value of
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
338 @code{buffer-offer-save}. (A user who says @samp{yes} to saving a
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
339 non-file buffer is asked to specify the file name to use.) The
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
340 @code{save-buffers-kill-emacs} function passes the value @code{t} for
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
341 @var{pred}.
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
342
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
343 If @var{pred} is neither @code{t} nor @code{nil}, then it should be
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
344 a function of no arguments. It will be called in each buffer to decide
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
345 whether to offer to save that buffer. If it returns a non-@code{nil}
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
346 value in a certain buffer, that means do offer to save that buffer.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
347 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
348
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
349 @deffn Command write-file filename &optional confirm
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
350 This function writes the current buffer into file @var{filename}, makes
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
351 the buffer visit that file, and marks it not modified. Then it renames
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 the buffer based on @var{filename}, appending a string like @samp{<2>}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 if necessary to make a unique buffer name. It does most of this work by
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
354 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
355 @code{save-buffer}.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
356
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
357 If @var{confirm} is non-@code{nil}, that means to ask for confirmation
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
358 before overwriting an existing file.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360
15913
f415fdc67ad3 Add xrefs from Saving Buffers to Format Conversion and Saving
Richard M. Stallman <rms@gnu.org>
parents: 15765
diff changeset
361 Saving a buffer runs several hooks. It also performs format
f415fdc67ad3 Add xrefs from Saving Buffers to Format Conversion and Saving
Richard M. Stallman <rms@gnu.org>
parents: 15765
diff changeset
362 conversion (@pxref{Format Conversion}), and may save text properties in
f415fdc67ad3 Add xrefs from Saving Buffers to Format Conversion and Saving
Richard M. Stallman <rms@gnu.org>
parents: 15765
diff changeset
363 ``annotations'' (@pxref{Saving Properties}).
f415fdc67ad3 Add xrefs from Saving Buffers to Format Conversion and Saving
Richard M. Stallman <rms@gnu.org>
parents: 15765
diff changeset
364
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
365 @defvar write-file-functions
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
366 The value of this variable is a list of functions to be called before
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
367 writing out a buffer to its visited file. If one of them returns
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
368 non-@code{nil}, the file is considered already written and the rest of
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369 the functions are not called, nor is the usual code for writing the file
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
370 executed.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
371
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
372 If a function in @code{write-file-functions} returns non-@code{nil}, it
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
373 is responsible for making a backup file (if that is appropriate).
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 To do so, execute the following code:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
376 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
377 (or buffer-backed-up (backup-buffer))
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
378 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
380 You might wish to save the file modes value returned by
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 @code{backup-buffer} and use that to set the mode bits of the file that
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382 you write. This is what @code{save-buffer} normally does.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
383
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
384 The hook functions in @code{write-file-functions} are also responsible for
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
385 encoding the data (if desired): they must choose a suitable coding
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
386 system (@pxref{Lisp and Coding Systems}), perform the encoding
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
387 (@pxref{Explicit Encoding}), and set @code{last-coding-system-used} to
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
388 the coding system that was used (@pxref{Encoding and I/O}).
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
389
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
390 If you set this hook locally in a buffer, it is assumed to be
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
391 associated with the file or the way the contents of the buffer were
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
392 obtained. Thus the variable is marked as a permanent local, so that
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
393 changing the major mode does not alter a buffer-local value. On the
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
394 other hand, calling @code{set-visited-file-name} will reset it.
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
395 If this is not what you want, you might like to use
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
396 @code{write-contents-functions} instead.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
397
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
398 Even though this is not a normal hook, you can use @code{add-hook} and
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399 @code{remove-hook} to manipulate the list. @xref{Hooks}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
400 @end defvar
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
401
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
402 @c Emacs 19 feature
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
403 @defvar write-contents-functions
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
404 This works just like @code{write-file-functions}, but it is intended for
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
405 hooks that pertain to the contents of the file, as opposed to hooks that
8364
f40f688148d1 entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8118
diff changeset
406 pertain to where the file came from. Such hooks are usually set up by
14152
9c9debb5950f Clarify write-contents-hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12674
diff changeset
407 major modes, as buffer-local bindings for this variable.
9c9debb5950f Clarify write-contents-hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12674
diff changeset
408
9c9debb5950f Clarify write-contents-hooks.
Richard M. Stallman <rms@gnu.org>
parents: 12674
diff changeset
409 This variable automatically becomes buffer-local whenever it is set;
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
410 switching to a new major mode always resets this variable.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
411 @end defvar
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
412
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
413 @c Emacs 19 feature
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
414 @defvar after-save-hook
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 This normal hook runs after a buffer has been saved in its visited file.
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
416 One use of this hook is in Fast Lock mode; it uses this hook to save the
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
417 highlighting information in a cache file.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418 @end defvar
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420 @defvar file-precious-flag
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
421 If this variable is non-@code{nil}, then @code{save-buffer} protects
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 against I/O errors while saving by writing the new file to a temporary
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
423 name instead of the name it is supposed to have, and then renaming it to
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424 the intended name after it is clear there are no errors. This procedure
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
425 prevents problems such as a lack of disk space from resulting in an
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
426 invalid file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
427
12226
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
428 As a side effect, backups are necessarily made by copying. @xref{Rename
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
429 or Copy}. Yet, at the same time, saving a precious file always breaks
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
430 all hard links between the file you save and other file names.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
431
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
432 Some modes give this variable a non-@code{nil} buffer-local value
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
433 in particular buffers.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
434 @end defvar
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
435
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436 @defopt require-final-newline
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
437 This variable determines whether files may be written out that do
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
438 @emph{not} end with a newline. If the value of the variable is
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439 @code{t}, then @code{save-buffer} silently adds a newline at the end of
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
440 the file whenever the buffer being saved does not already end in one.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
441 If the value of the variable is non-@code{nil}, but not @code{t}, then
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 @code{save-buffer} asks the user whether to add a newline each time the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
443 case arises.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
445 If the value of the variable is @code{nil}, then @code{save-buffer}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
446 doesn't add newlines at all. @code{nil} is the default value, but a few
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
447 major modes set it to @code{t} in particular buffers.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448 @end defopt
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
450 See also the function @code{set-visited-file-name} (@pxref{Buffer File
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
451 Name}).
15765
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
452
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
453 @node Reading from Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
454 @comment node-name, next, previous, up
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
455 @section Reading from Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 You can copy a file from the disk and insert it into a buffer
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 using the @code{insert-file-contents} function. Don't use the user-level
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 command @code{insert-file} in a Lisp program, as that sets the mark.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 @defun insert-file-contents filename &optional visit beg end replace
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
462 This function inserts the contents of file @var{filename} into the
12226
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
463 current buffer after point. It returns a list of the absolute file name
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464 and the length of the data inserted. An error is signaled if
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 @var{filename} is not the name of a file that can be read.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
467 The function @code{insert-file-contents} checks the file contents
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
468 against the defined file formats, and converts the file contents if
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
469 appropriate. @xref{Format Conversion}. It also calls the functions in
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
470 the list @code{after-insert-file-functions}; see @ref{Saving
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
471 Properties}. Normally, one of the functions in the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
472 @code{after-insert-file-functions} list determines the coding system
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
473 (@pxref{Coding Systems}) used for decoding the file's contents.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 If @var{visit} is non-@code{nil}, this function additionally marks the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 buffer as unmodified and sets up various fields in the buffer so that it
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 is visiting the file @var{filename}: these include the buffer's visited
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478 file name and its last save file modtime. This feature is used by
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
479 @code{find-file-noselect} and you probably should not use it yourself.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
481 If @var{beg} and @var{end} are non-@code{nil}, they should be integers
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 specifying the portion of the file to insert. In this case, @var{visit}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 must be @code{nil}. For example,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
485 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486 (insert-file-contents filename nil 0 500)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
488
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
489 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
490 inserts the first 500 characters of a file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 If the argument @var{replace} is non-@code{nil}, it means to replace the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
493 contents of the buffer (actually, just the accessible portion) with the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
494 contents of the file. This is better than simply deleting the buffer
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495 contents and inserting the whole file, because (1) it preserves some
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
496 marker positions and (2) it puts less data in the undo list.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
497
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
498 It is possible to read a special file (such as a FIFO or an I/O device)
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
499 with @code{insert-file-contents}, as long as @var{replace} and
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
500 @var{visit} are @code{nil}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
501 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
502
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
503 @defun insert-file-contents-literally filename &optional visit beg end replace
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
504 This function works like @code{insert-file-contents} except that it does
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
505 not do format decoding (@pxref{Format Conversion}), does not do
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
506 character code conversion (@pxref{Coding Systems}), does not run
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
507 @code{find-file-hook}, does not perform automatic uncompression, and so
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
508 on.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
509 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
510
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511 If you want to pass a file name to another process so that another
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512 program can read the file, use the function @code{file-local-copy}; see
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
513 @ref{Magic File Names}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
514
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515 @node Writing to Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516 @comment node-name, next, previous, up
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517 @section Writing to Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519 You can write the contents of a buffer, or part of a buffer, directly
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 to a file on disk using the @code{append-to-file} and
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521 @code{write-region} functions. Don't use these functions to write to
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522 files that are being visited; that could cause confusion in the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 mechanisms for visiting.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
524
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 @deffn Command append-to-file start end filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 This function appends the contents of the region delimited by
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 @var{start} and @var{end} in the current buffer to the end of file
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
528 @var{filename}. If that file does not exist, it is created. This
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
529 function returns @code{nil}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
530
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
531 An error is signaled if @var{filename} specifies a nonwritable file,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
532 or a nonexistent file in a directory where files cannot be created.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
533 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
534
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
535 @deffn Command write-region start end filename &optional append visit lockname mustbenew
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
536 This function writes the region delimited by @var{start} and @var{end}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
537 in the current buffer into the file specified by @var{filename}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
538
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
539 @c Emacs 19 feature
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 If @var{start} is a string, then @code{write-region} writes or appends
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
541 that string, rather than text from the buffer. @var{end} is ignored in
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
542 this case.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
543
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
544 If @var{append} is non-@code{nil}, then the specified text is appended
28853
3259733d5ea0 write-region change
Dave Love <fx@gnu.org>
parents: 28681
diff changeset
545 to the existing file contents (if any). Starting in Emacs 21, if
3259733d5ea0 write-region change
Dave Love <fx@gnu.org>
parents: 28681
diff changeset
546 @var{append} is an integer, then @code{write-region} seeks to that byte
3259733d5ea0 write-region change
Dave Love <fx@gnu.org>
parents: 28681
diff changeset
547 offset from the start of the file and writes the data from there.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
549 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
550 for confirmation if @var{filename} names an existing file.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
551 Starting in Emacs 21, if @var{mustbenew} is the symbol @code{excl},
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
552 then @code{write-region} does not ask for confirmation, but instead
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
553 it signals an error @code{file-already-exists} if the file already
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
554 exists.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
555
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
556 The test for an existing file, when @var{mustbenew} is @code{excl}, uses
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
557 a special system feature. At least for files on a local disk, there is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
558 no chance that some other program could create a file of the same name
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
559 before Emacs does, without Emacs's noticing.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
560
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 If @var{visit} is @code{t}, then Emacs establishes an association
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562 between the buffer and the file: the buffer is then visiting that file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 It also sets the last file modification time for the current buffer to
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 @var{filename}'s modtime, and marks the buffer as not modified. This
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
565 feature is used by @code{save-buffer}, but you probably should not use
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
566 it yourself.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
567
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
568 @c Emacs 19 feature
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
569 If @var{visit} is a string, it specifies the file name to visit. This
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
570 way, you can write the data to one file (@var{filename}) while recording
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571 the buffer as visiting another file (@var{visit}). The argument
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572 @var{visit} is used in the echo area message and also for file locking;
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573 @var{visit} is stored in @code{buffer-file-name}. This feature is used
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
574 to implement @code{file-precious-flag}; don't use it yourself unless you
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 really know what you're doing.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
577 The optional argument @var{lockname}, if non-@code{nil}, specifies the
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
578 file name to use for purposes of locking and unlocking, overriding
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
579 @var{filename} and @var{visit} for that purpose.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
580
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
581 The function @code{write-region} converts the data which it writes to
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
582 the appropriate file formats specified by @code{buffer-file-format}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
583 @xref{Format Conversion}. It also calls the functions in the list
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
584 @code{write-region-annotate-functions}; see @ref{Saving Properties}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
586 Normally, @code{write-region} displays the message @samp{Wrote
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587 @var{filename}} in the echo area. If @var{visit} is neither @code{t}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 nor @code{nil} nor a string, then this message is inhibited. This
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589 feature is useful for programs that use files for internal purposes,
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
590 files that the user does not need to know about.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
591 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
592
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
593 @defmac with-temp-file file body...
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
594 The @code{with-temp-file} macro evaluates the @var{body} forms with a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
595 temporary buffer as the current buffer; then, at the end, it writes the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
596 buffer contents into file @var{file}. It kills the temporary buffer
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
597 when finished, restoring the buffer that was current before the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
598 @code{with-temp-file} form. Then it returns the value of the last form
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
599 in @var{body}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
600
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
601 The current buffer is restored even in case of an abnormal exit via
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
602 @code{throw} or error (@pxref{Nonlocal Exits}).
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
603
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
604 See also @code{with-temp-buffer} in @ref{Current Buffer}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
605 @end defmac
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
606
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
607 @node File Locks
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
608 @section File Locks
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609 @cindex file locks
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
611 When two users edit the same file at the same time, they are likely to
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
612 interfere with each other. Emacs tries to prevent this situation from
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 arising by recording a @dfn{file lock} when a file is being modified.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 Emacs can then detect the first attempt to modify a buffer visiting a
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 file that is locked by another Emacs job, and ask the user what to do.
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
616 The file lock is really a file, a symbolic link with a special name,
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
617 stored in the same directory as the file you are editing.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
619 When you access files using NFS, there may be a small probability that
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
620 you and another user will both lock the same file ``simultaneously''.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
621 If this happens, it is possible for the two users to make changes
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
622 simultaneously, but Emacs will still warn the user who saves second.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
623 Also, the detection of modification of a buffer visiting a file changed
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
624 on disk catches some cases of simultaneous editing; see
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
625 @ref{Modification Time}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
627 @defun file-locked-p filename
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
628 This function returns @code{nil} if the file @var{filename} is not
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
629 locked. It returns @code{t} if it is locked by this Emacs process, and
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
630 it returns the name of the user who has locked it if it is locked by
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
631 some other job.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635 (file-locked-p "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
637 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
638 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
639 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
640
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
641 @defun lock-buffer &optional filename
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
642 This function locks the file @var{filename}, if the current buffer is
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
643 modified. The argument @var{filename} defaults to the current buffer's
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
644 visited file. Nothing is done if the current buffer is not visiting a
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
645 file, or is not modified.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
646 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
647
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
648 @defun unlock-buffer
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
649 This function unlocks the file being visited in the current buffer,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 if the buffer is modified. If the buffer is not modified, then
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651 the file should not be locked, so this function does nothing. It also
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652 does nothing if the current buffer is not visiting a file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
655 File locking is not supported on some systems. On systems that do not
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
656 support it, the functions @code{lock-buffer}, @code{unlock-buffer} and
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
657 @code{file-locked-p} do nothing and return @code{nil}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
658
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659 @defun ask-user-about-lock file other-user
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
660 This function is called when the user tries to modify @var{file}, but it
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
661 is locked by another user named @var{other-user}. The default
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
662 definition of this function asks the user to say what to do. The value
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
663 this function returns determines what Emacs does next:
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
664
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
665 @itemize @bullet
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
666 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
667 A value of @code{t} says to grab the lock on the file. Then
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668 this user may edit the file and @var{other-user} loses the lock.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 A value of @code{nil} says to ignore the lock and let this
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 user edit the file anyway.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
674 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
675 @kindex file-locked
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
676 This function may instead signal a @code{file-locked} error, in which
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677 case the change that the user was about to make does not take place.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
679 The error message for this error looks like this:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
681 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
682 @error{} File is locked: @var{file} @var{other-user}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
683 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
684
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686 where @code{file} is the name of the file and @var{other-user} is the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
687 name of the user who has locked the file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688 @end itemize
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
690 If you wish, you can replace the @code{ask-user-about-lock} function
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
691 with your own version that makes the decision in another way. The code
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692 for its usual definition is in @file{userlock.el}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695 @node Information about Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
696 @section Information about Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
697
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
698 The functions described in this section all operate on strings that
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
699 designate file names. All the functions have names that begin with the
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
700 word @samp{file}. These functions all return information about actual
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
701 files or directories, so their arguments must all exist as actual files
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
702 or directories unless otherwise noted.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
703
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
704 @menu
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 * Testing Accessibility:: Is a given file readable? Writable?
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706 * Kinds of Files:: Is it a directory? A symbolic link?
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 * Truenames:: Eliminating symbolic links from a file name.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 * File Attributes:: How large is it? Any other names? Etc.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
709 @end menu
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
710
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
711 @node Testing Accessibility
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712 @comment node-name, next, previous, up
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713 @subsection Testing Accessibility
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
714 @cindex accessibility of a file
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
715 @cindex file accessibility
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717 These functions test for permission to access a file in specific ways.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719 @defun file-exists-p filename
51654
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
720 This function returns @code{t} if a file named @var{filename} appears
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
721 to exist. This does not mean you can necessarily read the file, only
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
722 that you can find out its attributes. (On Unix and GNU/Linux, this is
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
723 true if the file exists and you have execute permission on the
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
724 containing directories, regardless of the protection of the file
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
725 itself.)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
726
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 If the file does not exist, or if fascist access control policies
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 prevent you from finding the attributes of the file, this function
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 returns @code{nil}.
51654
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
730
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
731 Directories are files, so @code{file-exists-p} returns @code{t} when
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
732 given a directory name. However, symbolic links are treated
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
733 specially; @code{file-exists-p} returns @code{t} for a symbolic link
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
734 name only if the target file exists.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737 @defun file-readable-p filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
738 This function returns @code{t} if a file named @var{filename} exists
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739 and you can read it. It returns @code{nil} otherwise.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
740
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
743 (file-readable-p "files.texi")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
745 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747 (file-exists-p "/usr/spool/mqueue")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
749 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
750 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
751 (file-readable-p "/usr/spool/mqueue")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
752 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757 @c Emacs 19 feature
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
758 @defun file-executable-p filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
759 This function returns @code{t} if a file named @var{filename} exists and
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
760 you can execute it. It returns @code{nil} otherwise. On Unix and
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
761 GNU/Linux, if the file is a directory, execute permission means you can
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
762 check the existence and attributes of files inside the directory, and
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
763 open those files if their modes permit.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
766 @defun file-writable-p filename
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
767 This function returns @code{t} if the file @var{filename} can be written
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
768 or created by you, and @code{nil} otherwise. A file is writable if the
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
769 file exists and you can write it. It is creatable if it does not exist,
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
770 but the specified directory does exist and you can write in that
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
771 directory.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
772
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
773 In the third example below, @file{foo} is not writable because the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
774 parent directory does not exist, even though the user could create such
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
775 a directory.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
776
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
777 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
779 (file-writable-p "~/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
780 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
782 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
783 (file-writable-p "/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
784 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
785 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
786 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787 (file-writable-p "~/no-such-dir/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
789 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793 @c Emacs 19 feature
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794 @defun file-accessible-directory-p dirname
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795 This function returns @code{t} if you have permission to open existing
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
796 files in the directory whose name as a file is @var{dirname}; otherwise
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
797 (or if there is no such directory), it returns @code{nil}. The value
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
798 of @var{dirname} may be either a directory name or the file name of a
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
799 file which is a directory.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801 Example: after the following,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804 (file-accessible-directory-p "/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
805 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
806 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
807
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809 we can deduce that any attempt to read a file in @file{/foo/} will
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 give an error.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
812
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
813 @defun access-file filename string
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
814 This function opens file @var{filename} for reading, then closes it and
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
815 returns @code{nil}. However, if the open fails, it signals an error
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
816 using @var{string} as the error message text.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
817 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
818
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
819 @defun file-ownership-preserved-p filename
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
820 This function returns @code{t} if deleting the file @var{filename} and
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
821 then creating it anew would keep the file's owner unchanged.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
822 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
823
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824 @defun file-newer-than-file-p filename1 filename2
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
825 @cindex file age
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826 @cindex file modification time
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
827 This function returns @code{t} if the file @var{filename1} is
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828 newer than file @var{filename2}. If @var{filename1} does not
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 exist, it returns @code{nil}. If @var{filename2} does not exist,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 it returns @code{t}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
832 In the following example, assume that the file @file{aug-19} was written
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
833 on the 19th, @file{aug-20} was written on the 20th, and the file
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
834 @file{no-file} doesn't exist at all.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838 (file-newer-than-file-p "aug-19" "aug-20")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
840 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
841 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 (file-newer-than-file-p "aug-20" "aug-19")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
844 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
845 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846 (file-newer-than-file-p "aug-19" "no-file")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
848 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
849 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
850 (file-newer-than-file-p "no-file" "aug-19")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 You can use @code{file-attributes} to get a file's last modification
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856 time as a list of two numbers. @xref{File Attributes}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 @node Kinds of Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860 @comment node-name, next, previous, up
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 @subsection Distinguishing Kinds of Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
863 This section describes how to distinguish various kinds of files, such
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
864 as directories, symbolic links, and ordinary files.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
865
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
866 @defun file-symlink-p filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
867 @cindex file symbolic links
50501
3bf63c244c44 (Kinds of Files): Correct return value of file-symlink-p.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
868 If the file @var{filename} is a symbolic link, the
3bf63c244c44 (Kinds of Files): Correct return value of file-symlink-p.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
869 @code{file-symlink-p} function returns the link target as a string.
3bf63c244c44 (Kinds of Files): Correct return value of file-symlink-p.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
870 (Determining the file name that the link points to from the target is
3bf63c244c44 (Kinds of Files): Correct return value of file-symlink-p.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
871 nontrivial.)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
872
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
873 If the file @var{filename} is not a symbolic link (or there is no such file),
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
874 @code{file-symlink-p} returns @code{nil}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
875
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
876 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
877 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
878 (file-symlink-p "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
879 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
880 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
881 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
882 (file-symlink-p "sym-link")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
883 @result{} "foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
884 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
885 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
886 (file-symlink-p "sym-link2")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887 @result{} "sym-link"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
888 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
889 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
890 (file-symlink-p "/bin")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
891 @result{} "/pub/bin"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
892 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
893 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
894
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
895 @c !!! file-symlink-p: should show output of ls -l for comparison
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
896 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
898 @defun file-directory-p filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
899 This function returns @code{t} if @var{filename} is the name of an
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
900 existing directory, @code{nil} otherwise.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
902 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
903 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904 (file-directory-p "~rms")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
908 (file-directory-p "~rms/lewis/files.texi")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
909 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
911 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
912 (file-directory-p "~rms/lewis/no-such-file")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
913 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
914 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
915 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
916 (file-directory-p "$HOME")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
918 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
920 (file-directory-p
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
921 (substitute-in-file-name "$HOME"))
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
922 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
923 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
926
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
927 @defun file-regular-p filename
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
928 This function returns @code{t} if the file @var{filename} exists and is
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
929 a regular file (not a directory, named pipe, terminal, or
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
930 other I/O device).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
931 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
932
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
933 @node Truenames
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934 @subsection Truenames
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935 @cindex truename (of file)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937 @c Emacs 19 features
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938 The @dfn{truename} of a file is the name that you get by following
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
939 symbolic links at all levels until none remain, then simplifying away
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
940 @samp{.}@: and @samp{..}@: appearing as name components. This results
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
941 in a sort of canonical name for the file. A file does not always have a
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
942 unique truename; the number of distinct truenames a file has is equal to
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
943 the number of hard links to the file. However, truenames are useful
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
944 because they eliminate symbolic links as a cause of name variation.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946 @defun file-truename filename
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
947 The function @code{file-truename} returns the truename of the file
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
948 @var{filename}. The argument must be an absolute file name.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
949 @end defun
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
950
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
951 @defun file-chase-links filename
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
952 This function follows symbolic links, starting with @var{filename},
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
953 until it finds a file name which is not the name of a symbolic link.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
954 Then it returns that file name.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
955 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
956
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
957 To illustrate the difference between @code{file-chase-links} and
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
958 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
959 the directory @file{/home/foo}, and @file{/home/foo/hello} is an
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
960 ordinary file (or at least, not a symbolic link) or nonexistent. Then
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
961 we would have:
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
962
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
963 @example
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
964 (file-chase-links "/usr/foo/hello")
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
965 ;; @r{This does not follow the links in the parent directories.}
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
966 @result{} "/usr/foo/hello"
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
967 (file-truename "/usr/foo/hello")
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
968 ;; @r{Assuming that @file{/home} is not a symbolic link.}
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
969 @result{} "/home/foo/hello"
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
970 @end example
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
971
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972 @xref{Buffer File Name}, for related information.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974 @node File Attributes
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
975 @comment node-name, next, previous, up
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976 @subsection Other Information about Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
978 This section describes the functions for getting detailed information
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
979 about a file, other than its contents. This information includes the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980 mode bits that control access permission, the owner and group numbers,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
981 the number of names, the inode number, the size, and the times of access
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
982 and modification.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984 @defun file-modes filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985 @cindex permission
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986 @cindex file attributes
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 This function returns the mode bits of @var{filename}, as an integer.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 The mode bits are also called the file permissions, and they specify
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
989 access control in the usual Unix fashion. If the low-order bit is 1,
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
990 then the file is executable by all users, if the second-lowest-order bit
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
991 is 1, then the file is writable by all users, etc.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
992
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
993 The highest value returnable is 4095 (7777 octal), meaning that
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
994 everyone has read, write, and execute permission, that the @sc{suid} bit
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
995 is set for both others and group, and that the sticky bit is set.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
996
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
997 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999 (file-modes "~/junk/diffs")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 @result{} 492 ; @r{Decimal integer.}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1002 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1003 (format "%o" 492)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1004 @result{} "754" ; @r{Convert to octal.}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1005 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1007 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1008 (set-file-modes "~/junk/diffs" 438)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1009 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1010 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1011
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1012 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1013 (format "%o" 438)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1014 @result{} "666" ; @r{Convert to octal.}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1016
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1017 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1018 % ls -l diffs
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1020 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1021 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1022 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1023
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1024 @defun file-nlinks filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1025 This functions returns the number of names (i.e., hard links) that
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1026 file @var{filename} has. If the file does not exist, then this function
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1027 returns @code{nil}. Note that symbolic links have no effect on this
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1028 function, because they are not considered to be names of the files they
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1029 link to.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1030
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1031 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1032 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1033 % ls -l foo*
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1034 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1035 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1036 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1037
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1038 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1039 (file-nlinks "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1040 @result{} 2
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1041 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1043 (file-nlinks "doesnt-exist")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1044 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1045 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1046 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1047 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1048
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1049 @defun file-attributes filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1050 This function returns a list of attributes of file @var{filename}. If
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1051 the specified file cannot be opened, it returns @code{nil}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1053 The elements of the list, in order, are:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1054
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1055 @enumerate 0
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1056 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057 @code{t} for a directory, a string for a symbolic link (the name
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 linked to), or @code{nil} for a text file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1059
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 @c Wordy so as to prevent an overfull hbox. --rjc 15mar92
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062 The number of names the file has. Alternate names, also known as hard
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063 links, can be created by using the @code{add-name-to-file} function
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1064 (@pxref{Changing Files}).
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067 The file's @sc{uid}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1069 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1070 The file's @sc{gid}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1071
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1072 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1073 The time of last access, as a list of two integers.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1074 The first integer has the high-order 16 bits of time,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1075 the second has the low 16 bits. (This is similar to the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1076 value of @code{current-time}; see @ref{Time of Day}.)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1077
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1078 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1079 The time of last modification as a list of two integers (as above).
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1080
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1081 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1082 The time of last status change as a list of two integers (as above).
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1083
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084 @item
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
1085 The size of the file in bytes. If the size is too large to fit in a
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
1086 Lisp integer, this is a floating point number.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1087
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1088 @item
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
1089 The file's modes, as a string of ten letters or dashes,
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1090 as in @samp{ls -l}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1091
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1092 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1093 @code{t} if the file's @sc{gid} would change if file were
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1094 deleted and recreated; @code{nil} otherwise.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1095
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1096 @item
17919
eb712b69e495 The inode number can be an integer.
Richard M. Stallman <rms@gnu.org>
parents: 17398
diff changeset
1097 The file's inode number. If possible, this is an integer. If the inode
eb712b69e495 The inode number can be an integer.
Richard M. Stallman <rms@gnu.org>
parents: 17398
diff changeset
1098 number is too large to be represented as an integer in Emacs Lisp, then
eb712b69e495 The inode number can be an integer.
Richard M. Stallman <rms@gnu.org>
parents: 17398
diff changeset
1099 the value has the form @code{(@var{high} . @var{low})}, where @var{low}
eb712b69e495 The inode number can be an integer.
Richard M. Stallman <rms@gnu.org>
parents: 17398
diff changeset
1100 holds the low 16 bits.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1102 @item
39296
5f4f6cf4a868 (File Attributes): Document that the device number can also be a cons cell.
Eli Zaretskii <eliz@gnu.org>
parents: 37582
diff changeset
1103 The file system number of the file system that the file is in.
5f4f6cf4a868 (File Attributes): Document that the device number can also be a cons cell.
Eli Zaretskii <eliz@gnu.org>
parents: 37582
diff changeset
1104 Depending on the magnitude of the value, this can be either an integer
5f4f6cf4a868 (File Attributes): Document that the device number can also be a cons cell.
Eli Zaretskii <eliz@gnu.org>
parents: 37582
diff changeset
1105 or a cons cell, in the same manner as the inode number. This element
5f4f6cf4a868 (File Attributes): Document that the device number can also be a cons cell.
Eli Zaretskii <eliz@gnu.org>
parents: 37582
diff changeset
1106 and the file's inode number together give enough information to
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
1107 distinguish any two files on the system---no two files can have the same
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
1108 values for both of these numbers.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1109 @end enumerate
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1110
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1111 For example, here are the file attributes for @file{files.texi}:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1112
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1113 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1114 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1115 (file-attributes "files.texi")
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
1116 @result{} (nil 1 2235 75
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
1117 (8489 20284)
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
1118 (8489 20284)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1119 (8489 20285)
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
1120 14906 "-rw-rw-rw-"
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1121 nil 129500 -32252)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1122 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1124
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1125 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1126 and here is how the result is interpreted:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1127
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128 @table @code
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1129 @item nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130 is neither a directory nor a symbolic link.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 @item 1
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1133 has only one name (the name @file{files.texi} in the current default
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134 directory).
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136 @item 2235
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137 is owned by the user with @sc{uid} 2235.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1138
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1139 @item 75
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1140 is in the group with @sc{gid} 75.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1141
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1142 @item (8489 20284)
12522
75d5cd591947 Fix minor error.
Richard M. Stallman <rms@gnu.org>
parents: 12226
diff changeset
1143 was last accessed on Aug 19 00:09.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1144
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1145 @item (8489 20284)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1146 was last modified on Aug 19 00:09.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1147
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1148 @item (8489 20285)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1149 last had its inode changed on Aug 19 00:09.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1150
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1151 @item 14906
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1152 is 14906 bytes long. (It may not contain 14906 characters, though,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1153 if some of the bytes belong to multibyte sequences.)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1154
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1155 @item "-rw-rw-rw-"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1156 has a mode of read and write access for the owner, group, and world.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1157
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1158 @item nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1159 would retain the same @sc{gid} if it were recreated.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1160
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1161 @item 129500
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1162 has an inode number of 129500.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163 @item -32252
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164 is on file system number -32252.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1165 @end table
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1166 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1167
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1168 @node Changing Files
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1169 @section Changing File Names and Attributes
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1170 @cindex renaming files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1171 @cindex copying files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1172 @cindex deleting files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1173 @cindex linking files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1174 @cindex setting modes of files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176 The functions in this section rename, copy, delete, link, and set the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1177 modes of files.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1178
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1179 In the functions that have an argument @var{newname}, if a file by the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1180 name of @var{newname} already exists, the actions taken depend on the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181 value of the argument @var{ok-if-already-exists}:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1182
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1183 @itemize @bullet
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1184 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1185 Signal a @code{file-already-exists} error if
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1186 @var{ok-if-already-exists} is @code{nil}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1187
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1188 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1189 Request confirmation if @var{ok-if-already-exists} is a number.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1190
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1191 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1192 Replace the old file without confirmation if @var{ok-if-already-exists}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1193 is any other value.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1194 @end itemize
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1195
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1196 @defun add-name-to-file oldname newname &optional ok-if-already-exists
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197 @cindex file with multiple names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1198 @cindex file hard link
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1199 This function gives the file named @var{oldname} the additional name
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1200 @var{newname}. This means that @var{newname} becomes a new ``hard
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1201 link'' to @var{oldname}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1202
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1203 In the first part of the following example, we list two files,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1204 @file{foo} and @file{foo3}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1205
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1206 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1207 @group
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1208 % ls -li fo*
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1209 81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1210 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1211 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1212 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1213
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
1214 Now we create a hard link, by calling @code{add-name-to-file}, then list
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
1215 the files again. This shows two names for one file, @file{foo} and
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
1216 @file{foo2}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1217
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1218 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1219 @group
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1220 (add-name-to-file "foo" "foo2")
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1221 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1222 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1223
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1224 @group
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1225 % ls -li fo*
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1226 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1227 81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1228 84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1229 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1230 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1232 Finally, we evaluate the following:
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1233
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1234 @example
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1235 (add-name-to-file "foo" "foo3" t)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1236 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1237
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1238 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1239 and list the files again. Now there are three names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1240 for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1241 contents of @file{foo3} are lost.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1242
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1243 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1244 @group
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1245 (add-name-to-file "foo1" "foo3")
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1246 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1248
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1249 @group
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1250 % ls -li fo*
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1251 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1252 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1253 81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1254 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1256
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1257 This function is meaningless on operating systems where multiple names
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1258 for one file are not allowed. Some systems implement multiple names
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1259 by copying the file instead.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1260
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1261 See also @code{file-nlinks} in @ref{File Attributes}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1262 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1263
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1264 @deffn Command rename-file filename newname &optional ok-if-already-exists
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265 This command renames the file @var{filename} as @var{newname}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1266
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1267 If @var{filename} has additional names aside from @var{filename}, it
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1268 continues to have those names. In fact, adding the name @var{newname}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1269 with @code{add-name-to-file} and then deleting @var{filename} has the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1270 same effect as renaming, aside from momentary intermediate states.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1271
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1272 In an interactive call, this function prompts for @var{filename} and
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1273 @var{newname} in the minibuffer; also, it requests confirmation if
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1274 @var{newname} already exists.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1275 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1276
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1277 @deffn Command copy-file oldname newname &optional ok-if-exists time
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1278 This command copies the file @var{oldname} to @var{newname}. An
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1279 error is signaled if @var{oldname} does not exist.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1280
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1281 If @var{time} is non-@code{nil}, then this function gives the new file
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1282 the same last-modified time that the old one has. (This works on only
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1283 some operating systems.) If setting the time gets an error,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1284 @code{copy-file} signals a @code{file-date-error} error.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1285
51558
5a85c7c1d3ab (Changing Files): copy-file copies file modes, too.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 51020
diff changeset
1286 This function copies the file modes, too.
5a85c7c1d3ab (Changing Files): copy-file copies file modes, too.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 51020
diff changeset
1287
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1288 In an interactive call, this function prompts for @var{filename} and
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1289 @var{newname} in the minibuffer; also, it requests confirmation if
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1290 @var{newname} already exists.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1291 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1292
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1293 @deffn Command delete-file filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1294 @pindex rm
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1295 This command deletes the file @var{filename}, like the shell command
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1296 @samp{rm @var{filename}}. If the file has multiple names, it continues
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1297 to exist under the other names.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1298
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1299 A suitable kind of @code{file-error} error is signaled if the file does
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1300 not exist, or is not deletable. (On Unix and GNU/Linux, a file is
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1301 deletable if its directory is writable.)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1302
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1303 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1304 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1305
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1306 @deffn Command make-symbolic-link filename newname &optional ok-if-exists
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1307 @pindex ln
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1308 @kindex file-already-exists
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1309 This command makes a symbolic link to @var{filename}, named
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1310 @var{newname}. This is like the shell command @samp{ln -s
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1311 @var{filename} @var{newname}}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1312
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
1313 In an interactive call, this function prompts for @var{filename} and
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
1314 @var{newname} in the minibuffer; also, it requests confirmation if
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
1315 @var{newname} already exists.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1316
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1317 This function is not available on systems that don't support symbolic
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1318 links.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1319 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1320
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1321 @defun define-logical-name varname string
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1322 This function defines the logical name @var{name} to have the value
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1323 @var{string}. It is available only on VMS.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1324 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1325
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1326 @defun set-file-modes filename mode
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1327 This function sets mode bits of @var{filename} to @var{mode} (which must
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
1328 be an integer). Only the low 12 bits of @var{mode} are used.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1329 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1330
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1331 @c Emacs 19 feature
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1332 @defun set-default-file-modes mode
47514
e0d6f0b369d1 Add `umask' to the concept index.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46956
diff changeset
1333 @cindex umask
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1334 This function sets the default file protection for new files created by
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1335 Emacs and its subprocesses. Every file created with Emacs initially has
28074
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1336 this protection, or a subset of it (@code{write-region} will not give a
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1337 file execute permission even if the default file protection allows
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1338 execute permission). On Unix and GNU/Linux, the default protection is
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1339 the bitwise complement of the ``umask'' value.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1340
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1341 The argument @var{mode} must be an integer. On most systems, only the
28074
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1342 low 9 bits of @var{mode} are meaningful. You can use the Lisp construct
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1343 for octal character codes to enter @var{mode}; for example,
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1344
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1345 @example
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1346 (set-default-file-modes ?\644)
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1347 @end example
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1348
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1349 Saving a modified version of an existing file does not count as creating
28074
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1350 the file; it preserves the existing file's mode, whatever that is. So
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1351 the default file protection has no effect.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1352 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1353
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1354 @defun default-file-modes
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1355 This function returns the current default protection value.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1356 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1357
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
1358 @cindex MS-DOS and file modes
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
1359 @cindex file modes and MS-DOS
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
1360 On MS-DOS, there is no such thing as an ``executable'' file mode bit.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1361 So Emacs considers a file executable if its name ends in one of the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1362 standard executable extensions, such as @file{.com}, @file{.bat},
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1363 @file{.exe}, and some others. Files that begin with the Unix-standard
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1364 @samp{#!} signature, such as shell and Perl scripts, are also considered
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1365 as executable files. This is reflected in the values returned by
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1366 @code{file-modes} and @code{file-attributes}. Directories are also
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1367 reported with executable bit set, for compatibility with Unix.
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
1368
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1369 @node File Names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1370 @section File Names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1371 @cindex file names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1372
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1373 Files are generally referred to by their names, in Emacs as elsewhere.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1374 File names in Emacs are represented as strings. The functions that
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1375 operate on a file all expect a file name argument.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1376
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1377 In addition to operating on files themselves, Emacs Lisp programs
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1378 often need to operate on file names; i.e., to take them apart and to use
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1379 part of a name to construct related file names. This section describes
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1380 how to manipulate file names.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1381
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1382 The functions in this section do not actually access files, so they
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1383 can operate on file names that do not refer to an existing file or
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1384 directory.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1385
28635
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1386 On MS-DOS and MS-Windows, these functions (like the function that
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1387 actually operate on files) accept MS-DOS or MS-Windows file-name syntax,
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1388 where backslashes separate the components, as well as Unix syntax; but
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1389 they always return Unix syntax. On VMS, these functions (and the ones
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1390 that operate on files) understand both VMS file-name syntax and Unix
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1391 syntax. This enables Lisp programs to specify file names in Unix syntax
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1392 and work properly on all systems without change.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1393
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1394 @menu
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1395 * File Name Components:: The directory part of a file name, and the rest.
46956
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1396 * Relative File Names:: Some file names are relative to a current directory.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1397 * Directory Names:: A directory's name as a directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1398 is different from its name as a file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1399 * File Name Expansion:: Converting relative file names to absolute ones.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1400 * Unique File Names:: Generating names for temporary files.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1401 * File Name Completion:: Finding the completions for a given file name.
15765
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
1402 * Standard File Names:: If your package uses a fixed file name,
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
1403 how to handle various operating systems simply.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1404 @end menu
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1405
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1406 @node File Name Components
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1407 @subsection File Name Components
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1408 @cindex directory part (of file name)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1409 @cindex nondirectory part (of file name)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1410 @cindex version number (in file name)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1411
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1412 The operating system groups files into directories. To specify a
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
1413 file, you must specify the directory and the file's name within that
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
1414 directory. Therefore, Emacs considers a file name as having two main
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
1415 parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
1416 (or @dfn{file name within the directory}). Either part may be empty.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
1417 Concatenating these two parts reproduces the original file name.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1418
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1419 On most systems, the directory part is everything up to and including
28635
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1420 the last slash (backslash is also allowed in input on MS-DOS or
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1421 MS-Windows); the nondirectory part is the rest. The rules in VMS syntax
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1422 are complicated.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1423
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1424 For some purposes, the nondirectory part is further subdivided into
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1425 the name proper and the @dfn{version number}. On most systems, only
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1426 backup files have version numbers in their names. On VMS, every file
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1427 has a version number, but most of the time the file name actually used
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1428 in Emacs omits the version number, so that version numbers in Emacs are
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1429 found mostly in directory lists.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1430
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1431 @defun file-name-directory filename
46956
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1432 This function returns the directory part of @var{filename}, as a
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1433 directory name (@pxref{Directory Names}), or @code{nil} if
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1434 @var{filename} does not include a directory part.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1435
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1436 On GNU and Unix systems, a string returned by this function always
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1437 ends in a slash. On MSDOS it can also end in a colon. On VMS, it
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1438 returns a string ending in one of the three characters @samp{:},
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1439 @samp{]}, or @samp{>}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1440
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1441 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1442 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1443 (file-name-directory "lewis/foo") ; @r{Unix example}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1444 @result{} "lewis/"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1445 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1446 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1447 (file-name-directory "foo") ; @r{Unix example}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1448 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1449 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1450 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1451 (file-name-directory "[X]FOO.TMP") ; @r{VMS example}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1452 @result{} "[X]"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1453 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1454 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1455 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1456
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457 @defun file-name-nondirectory filename
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1458 This function returns the nondirectory part of @var{filename}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1459
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1460 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1461 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1462 (file-name-nondirectory "lewis/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1463 @result{} "foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1464 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1465 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1466 (file-name-nondirectory "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1467 @result{} "foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1468 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1469 @group
46956
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1470 (file-name-nondirectory "lewis/")
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1471 @result{} ""
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1472 @end group
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1473 @group
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1474 ;; @r{The following example is accurate only on VMS.}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1475 (file-name-nondirectory "[X]FOO.TMP")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1476 @result{} "FOO.TMP"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1477 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1478 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1479 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1480
46956
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1481 @defun file-name-extension filename &optional period
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1482 This function returns @var{filename}'s final ``extension,'' if any,
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1483 after applying @code{file-name-sans-versions} to remove any
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1484 version/backup part. It returns @code{nil} for extensionless file
51654
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
1485 names such as @file{foo}. If @var{period} is non-@code{nil}, then the
46956
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1486 returned value includes the period that delimits the extension, and if
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1487 @var{filename} has no extension, the value is @code{""}. If the last
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1488 component of a file name begins with a @samp{.}, that @samp{.} doesn't
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1489 count as the beginning of an extension, so, for example,
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1490 @file{.emacs}'s ``extension'' is @code{nil}, not @samp{.emacs}.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1491 @end defun
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1492
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1493 @defun file-name-sans-versions filename &optional keep-backup-version
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1494 This function returns @var{filename} with any file version numbers,
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1495 backup version numbers, or trailing tildes discarded.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1496
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1497 If @var{keep-backup-version} is non-@code{nil}, then true file version
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1498 numbers understood as such by the file system are discarded from the
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1499 return value, but backup version numbers are kept.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1500
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1501 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1502 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1503 (file-name-sans-versions "~rms/foo.~1~")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1504 @result{} "~rms/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1505 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1506 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1507 (file-name-sans-versions "~rms/foo~")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1508 @result{} "~rms/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1509 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1510 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1511 (file-name-sans-versions "~rms/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1512 @result{} "~rms/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1513 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1514 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1515 ;; @r{The following example applies to VMS only.}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1516 (file-name-sans-versions "foo;23")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1517 @result{} "foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1518 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1519 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1520 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1521
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
1522 @defun file-name-sans-extension filename
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1523 This function returns @var{filename} minus its ``extension,'' if any.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1524 The extension, in a file name, is the part that starts with the last
40188
cd1cd95ca64e (File Name Components): Update the description of
Eli Zaretskii <eliz@gnu.org>
parents: 39883
diff changeset
1525 @samp{.} in the last name component, except if that @samp{.} is the
cd1cd95ca64e (File Name Components): Update the description of
Eli Zaretskii <eliz@gnu.org>
parents: 39883
diff changeset
1526 first character of the file name's last component. For example,
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1527
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1528 @example
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1529 (file-name-sans-extension "foo.lose.c")
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1530 @result{} "foo.lose"
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1531 (file-name-sans-extension "big.hack/foo")
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1532 @result{} "big.hack/foo"
40188
cd1cd95ca64e (File Name Components): Update the description of
Eli Zaretskii <eliz@gnu.org>
parents: 39883
diff changeset
1533 (file-name-sans-extension "/my/home/.emacs")
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
1534 @result{} "/my/home/.emacs"
40188
cd1cd95ca64e (File Name Components): Update the description of
Eli Zaretskii <eliz@gnu.org>
parents: 39883
diff changeset
1535 (file-name-sans-extension "/my/home/.emacs.el")
cd1cd95ca64e (File Name Components): Update the description of
Eli Zaretskii <eliz@gnu.org>
parents: 39883
diff changeset
1536 @result{} "/my/home/.emacs"
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1537 @end example
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
1538 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
1539
28635
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1540 @ignore
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
1541 Andrew Innes says that this
28635
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1542
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1543 @c @defvar directory-sep-char
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1544 @c @tindex directory-sep-char
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1545 This variable holds the character that Emacs normally uses to separate
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1546 file name components. The default value is @code{?/}, but on MS-Windows
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1547 you can set it to @code{?\\}; then the functions that transform file names
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1548 use backslashes in their output.
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1549
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1550 File names using backslashes work as input to Lisp primitives even on
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1551 MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1552 value of @code{?/}.
28608
c46c2efa3731 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28074
diff changeset
1553 @end defvar
28635
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1554 @end ignore
28608
c46c2efa3731 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28074
diff changeset
1555
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1556 @node Relative File Names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1557 @subsection Absolute and Relative File Names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1558 @cindex absolute file name
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1559 @cindex relative file name
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1560
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1561 All the directories in the file system form a tree starting at the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1562 root directory. A file name can specify all the directory names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1563 starting from the root of the tree; then it is called an @dfn{absolute}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1564 file name. Or it can specify the position of the file in the tree
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1565 relative to a default directory; then it is called a @dfn{relative} file
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1566 name. On Unix and GNU/Linux, an absolute file name starts with a slash
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1567 or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1568 MS-Windows, an absolute file name starts with a slash or a backslash, or
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1569 with a drive specification @samp{@var{x}:/}, where @var{x} is the
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1570 @dfn{drive letter}. The rules on VMS are complicated.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1571
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1572 @defun file-name-absolute-p filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1573 This function returns @code{t} if file @var{filename} is an absolute
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1574 file name, @code{nil} otherwise. On VMS, this function understands both
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1575 Unix syntax and VMS syntax.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1576
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1577 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1578 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1579 (file-name-absolute-p "~rms/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1580 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1581 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1582 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1583 (file-name-absolute-p "rms/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1584 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1585 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1586 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1587 (file-name-absolute-p "/user/rms/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1588 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1589 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1590 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1591 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1592
46956
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1593 @node Directory Names
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1594 @comment node-name, next, previous, up
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1595 @subsection Directory Names
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1596 @cindex directory name
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1597 @cindex file name of directory
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1598
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1599 A @dfn{directory name} is the name of a directory. A directory is
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1600 actually a kind of file, so it has a file name, which is related to
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1601 the directory name but not identical to it. (This is not quite the
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1602 same as the usual Unix terminology.) These two different names for
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1603 the same entity are related by a syntactic transformation. On GNU and
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1604 Unix systems, this is simple: a directory name ends in a slash (or
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1605 backslash), whereas the directory's name as a file lacks that slash.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1606 On MSDOS and VMS, the relationship is more complicated.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1607
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1608 The difference between a directory name and its name as a file is
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1609 subtle but crucial. When an Emacs variable or function argument is
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1610 described as being a directory name, a file name of a directory is not
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1611 acceptable. When @code{file-name-directory} returns a string, that is
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1612 always a directory name.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1613
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1614 The following two functions convert between directory names and file
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1615 names. They do nothing special with environment variable substitutions
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1616 such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1617
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1618 @defun file-name-as-directory filename
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1619 This function returns a string representing @var{filename} in a form
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1620 that the operating system will interpret as the name of a directory. On
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1621 most systems, this means appending a slash to the string (if it does not
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1622 already end in one). On VMS, the function converts a string of the form
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1623 @file{[X]Y.DIR.1} to the form @file{[X.Y]}.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1624
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1625 @example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1626 @group
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1627 (file-name-as-directory "~rms/lewis")
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1628 @result{} "~rms/lewis/"
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1629 @end group
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1630 @end example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1631 @end defun
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1632
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1633 @defun directory-file-name dirname
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1634 This function returns a string representing @var{dirname} in a form that
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1635 the operating system will interpret as the name of a file. On most
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1636 systems, this means removing the final slash (or backslash) from the
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1637 string. On VMS, the function converts a string of the form @file{[X.Y]}
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1638 to @file{[X]Y.DIR.1}.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1639
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1640 @example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1641 @group
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1642 (directory-file-name "~lewis/")
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1643 @result{} "~lewis"
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1644 @end group
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1645 @end example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1646 @end defun
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1647
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1648 Given a directory name, you can combine it with a relative file name
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1649 using @code{concat}:
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1650
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1651 @example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1652 (concat @var{dirname} @var{relfile})
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1653 @end example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1654
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1655 @noindent
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1656 Be sure to verify that the file name is relative before doing that.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1657 If you use an absolute file name, the results could be syntactically
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1658 invalid or refer to the wrong file.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1659
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1660 If you want to use a directory file name in making such a
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1661 combination, you must first convert it to a directory name using
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1662 @code{file-name-as-directory}:
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1663
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1664 @example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1665 (concat (file-name-as-directory @var{dirfile}) @var{relfile})
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1666 @end example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1667
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1668 @noindent
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1669 Don't try concatenating a slash by hand, as in
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1670
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1671 @example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1672 ;;; @r{Wrong!}
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1673 (concat @var{dirfile} "/" @var{relfile})
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1674 @end example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1675
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1676 @noindent
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1677 because this is not portable. Always use
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1678 @code{file-name-as-directory}.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1679
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1680 @cindex directory name abbreviation
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1681 Directory name abbreviations are useful for directories that are
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1682 normally accessed through symbolic links. Sometimes the users recognize
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1683 primarily the link's name as ``the name'' of the directory, and find it
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1684 annoying to see the directory's ``real'' name. If you define the link
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1685 name as an abbreviation for the ``real'' name, Emacs shows users the
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1686 abbreviation instead.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1687
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1688 @defvar directory-abbrev-alist
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1689 The variable @code{directory-abbrev-alist} contains an alist of
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1690 abbreviations to use for file directories. Each element has the form
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1691 @code{(@var{from} . @var{to})}, and says to replace @var{from} with
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1692 @var{to} when it appears in a directory name. The @var{from} string is
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1693 actually a regular expression; it should always start with @samp{^}.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1694 The function @code{abbreviate-file-name} performs these substitutions.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1695
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1696 You can set this variable in @file{site-init.el} to describe the
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1697 abbreviations appropriate for your site.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1698
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1699 Here's an example, from a system on which file system @file{/home/fsf}
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1700 and so on are normally accessed through symbolic links named @file{/fsf}
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1701 and so on.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1702
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1703 @example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1704 (("^/home/fsf" . "/fsf")
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1705 ("^/home/gp" . "/gp")
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1706 ("^/home/gd" . "/gd"))
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1707 @end example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1708 @end defvar
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1709
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1710 To convert a directory name to its abbreviation, use this
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1711 function:
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1712
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1713 @defun abbreviate-file-name filename
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1714 This function applies abbreviations from @code{directory-abbrev-alist}
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1715 to its argument, and substitutes @samp{~} for the user's home
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1716 directory. You can use it for directory names and for file names,
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1717 because it recognizes abbreviations even as part of the name.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1718 @end defun
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1719
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1720 @node File Name Expansion
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1721 @subsection Functions that Expand Filenames
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1722 @cindex expansion of file names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1723
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1724 @dfn{Expansion} of a file name means converting a relative file name
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1725 to an absolute one. Since this is done relative to a default directory,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1726 you must specify the default directory name as well as the file name to
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1727 be expanded. Expansion also simplifies file names by eliminating
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1728 redundancies such as @file{./} and @file{@var{name}/../}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1729
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1730 @defun expand-file-name filename &optional directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1731 This function converts @var{filename} to an absolute file name. If
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1732 @var{directory} is supplied, it is the default directory to start with
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1733 if @var{filename} is relative. (The value of @var{directory} should
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1734 itself be an absolute directory name; it may start with @samp{~}.)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1735 Otherwise, the current buffer's value of @code{default-directory} is
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1736 used. For example:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1737
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1738 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1739 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1740 (expand-file-name "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1741 @result{} "/xcssun/users/rms/lewis/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1742 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1743 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1744 (expand-file-name "../foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1745 @result{} "/xcssun/users/rms/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1746 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1747 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1748 (expand-file-name "foo" "/usr/spool/")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1749 @result{} "/usr/spool/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1750 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1751 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1752 (expand-file-name "$HOME/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1753 @result{} "/xcssun/users/rms/lewis/$HOME/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1754 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1755 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1756
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1757 Filenames containing @samp{.} or @samp{..} are simplified to their
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1758 canonical form:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1759
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1760 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1761 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1762 (expand-file-name "bar/../foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1763 @result{} "/xcssun/users/rms/lewis/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1764 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1765 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1766
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1767 Note that @code{expand-file-name} does @emph{not} expand environment
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1768 variables; only @code{substitute-in-file-name} does that.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1769 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1770
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1771 @c Emacs 19 feature
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1772 @defun file-relative-name filename &optional directory
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1773 This function does the inverse of expansion---it tries to return a
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
1774 relative name that is equivalent to @var{filename} when interpreted
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1775 relative to @var{directory}. If @var{directory} is omitted or
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1776 @code{nil}, it defaults to the current buffer's default directory.
17398
a5d9cbc4e2c5 (file-relative-name): Say correctly when the value is absolute.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1777
a5d9cbc4e2c5 (file-relative-name): Say correctly when the value is absolute.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1778 On some operating systems, an absolute file name begins with a device
a5d9cbc4e2c5 (file-relative-name): Say correctly when the value is absolute.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1779 name. On such systems, @var{filename} has no relative equivalent based
a5d9cbc4e2c5 (file-relative-name): Say correctly when the value is absolute.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1780 on @var{directory} if they start with two different device names. In
a5d9cbc4e2c5 (file-relative-name): Say correctly when the value is absolute.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1781 this case, @code{file-relative-name} returns @var{filename} in absolute
a5d9cbc4e2c5 (file-relative-name): Say correctly when the value is absolute.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
1782 form.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1783
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1784 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1785 (file-relative-name "/foo/bar" "/foo/")
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1786 @result{} "bar"
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1787 (file-relative-name "/foo/bar" "/hack/")
28681
bf112ad58dc7 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28635
diff changeset
1788 @result{} "../foo/bar"
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1789 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1790 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1791
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1792 @defvar default-directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1793 The value of this buffer-local variable is the default directory for the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1794 current buffer. It should be an absolute directory name; it may start
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1795 with @samp{~}. This variable is buffer-local in every buffer.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1796
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1797 @code{expand-file-name} uses the default directory when its second
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1798 argument is @code{nil}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1799
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1800 Aside from VMS, the value is always a string ending with a slash.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1801
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1802 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1803 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1804 default-directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1805 @result{} "/user/lewis/manual/"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1806 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1807 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1808 @end defvar
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1809
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1810 @defun substitute-in-file-name filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1811 This function replaces environment variables references in
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1812 @var{filename} with the environment variable values. Following standard
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1813 Unix shell syntax, @samp{$} is the prefix to substitute an environment
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1814 variable value.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1815
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1816 The environment variable name is the series of alphanumeric characters
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1817 (including underscores) that follow the @samp{$}. If the character following
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1818 the @samp{$} is a @samp{@{}, then the variable name is everything up to the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1819 matching @samp{@}}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1820
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1821 @c Wordy to avoid overfull hbox. --rjc 15mar92
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1822 Here we assume that the environment variable @code{HOME}, which holds
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1823 the user's home directory name, has value @samp{/xcssun/users/rms}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1824
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1825 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1826 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1827 (substitute-in-file-name "$HOME/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1828 @result{} "/xcssun/users/rms/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1829 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1830 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1831
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1832 After substitution, if a @samp{~} or a @samp{/} appears following a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1833 @samp{/}, everything before the following @samp{/} is discarded:
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1834
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1835 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1836 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1837 (substitute-in-file-name "bar/~/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1838 @result{} "~/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1839 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1840 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1841 (substitute-in-file-name "/usr/local/$HOME/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1842 @result{} "/xcssun/users/rms/foo"
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1843 ;; @r{@file{/usr/local/} has been discarded.}
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1844 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1845 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1846
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1847 On VMS, @samp{$} substitution is not done, so this function does nothing
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1848 on VMS except discard superfluous initial components as shown above.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1849 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1850
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1851 @node Unique File Names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1852 @subsection Generating Unique File Names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1853
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1854 Some programs need to write temporary files. Here is the usual way to
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1855 construct a name for such a file, starting in Emacs 21:
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1856
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1857 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1858 (make-temp-file @var{name-of-application})
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1859 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1860
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1861 @noindent
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1862 The job of @code{make-temp-file} is to prevent two different users or
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1863 two different jobs from trying to use the exact same file name.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1864
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1865 @defun make-temp-file prefix &optional dir-flag
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1866 @tindex make-temp-file
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1867 This function creates a temporary file and returns its name.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1868 The name starts with @var{prefix}; it also contains a number that is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1869 different in each Emacs job. If @var{prefix} is a relative file name,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1870 it is expanded against @code{temporary-file-directory}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1871
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1872 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1873 @group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1874 (make-temp-file "foo")
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1875 @result{} "/tmp/foo232J6v"
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1876 @end group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1877 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1878
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1879 When @code{make-temp-file} returns, the file has been created and is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1880 empty. At that point, you should write the intended contents into the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1881 file.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1882
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1883 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1884 an empty directory instead of an empty file.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1885
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1886 To prevent conflicts among different libraries running in the same
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1887 Emacs, each Lisp program that uses @code{make-temp-file} should have its
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1888 own @var{prefix}. The number added to the end of @var{prefix}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1889 distinguishes between the same application running in different Emacs
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1890 jobs. Additional added characters permit a large number of distinct
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1891 names even in one Emacs job.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1892 @end defun
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1893
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1894 The default directory for temporary files is controlled by the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1895 variable @code{temporary-file-directory}. This variable gives the user
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1896 a uniform way to specify the directory for all temporary files. Some
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1897 programs use @code{small-temporary-file-directory} instead, if that is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1898 non-@code{nil}. To use it, you should expand the prefix against
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1899 the proper directory before calling @code{make-temp-file}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1900
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1901 In older Emacs versions where @code{make-temp-file} does not exist,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1902 you should use @code{make-temp-name} instead:
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1903
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1904 @example
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1905 (make-temp-name
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1906 (expand-file-name @var{name-of-application}
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1907 temporary-file-directory))
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1908 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1909
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1910 @defun make-temp-name string
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1911 This function generates a string that can be used as a unique file name.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1912 The name starts with @var{string}, and contains a number that is
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1913 different in each Emacs job. It is like @code{make-temp-file} except
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1914 that it just constructs a name, and does not create a file. On MS-DOS,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1915 the @var{string} prefix can be truncated to fit into the 8+3 file-name
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1916 limits.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1917 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1918
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1919 @defvar temporary-file-directory
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1920 @cindex @code{TMPDIR} environment variable
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1921 @cindex @code{TMP} environment variable
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1922 @cindex @code{TEMP} environment variable
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1923 This variable specifies the directory name for creating temporary files.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1924 Its value should be a directory name (@pxref{Directory Names}), but it
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1925 is good for Lisp programs to cope if the value is a directory's file
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1926 name instead. Using the value as the second argument to
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1927 @code{expand-file-name} is a good way to achieve that.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1928
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1929 The default value is determined in a reasonable way for your operating
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1930 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1931 environment variables, with a fall-back to a system-dependent name if
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1932 none of these variables is defined.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1933
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1934 Even if you do not use @code{make-temp-name} to choose the temporary
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1935 file's name, you should still use this variable to decide which
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1936 directory to put the file in. However, if you expect the file to be
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1937 small, you should use @code{small-temporary-file-directory} first if
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1938 that is non-@code{nil}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1939 @end defvar
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1940
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1941 @tindex small-temporary-file-directory
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1942 @defvar small-temporary-file-directory
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1943 This variable (new in Emacs 21) specifies the directory name for
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1944 creating certain temporary files, which are likely to be small.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1945
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1946 If you want to write a temporary file which is likely to be small, you
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1947 should compute the directory like this:
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1948
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1949 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1950 (make-temp-file
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1951 (expand-file-name @var{prefix}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1952 (or small-temporary-file-directory
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1953 temporary-file-directory)))
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1954 @end example
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1955 @end defvar
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1956
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1957 @node File Name Completion
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1958 @subsection File Name Completion
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1959 @cindex file name completion subroutines
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1960 @cindex completion, file name
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1961
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1962 This section describes low-level subroutines for completing a file
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1963 name. For other completion functions, see @ref{Completion}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1964
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1965 @defun file-name-all-completions partial-filename directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1966 This function returns a list of all possible completions for a file
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1967 whose name starts with @var{partial-filename} in directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1968 @var{directory}. The order of the completions is the order of the files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1969 in the directory, which is unpredictable and conveys no useful
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1970 information.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1971
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1972 The argument @var{partial-filename} must be a file name containing no
28635
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1973 directory part and no slash (or backslash on some systems). The current
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1974 buffer's default directory is prepended to @var{directory}, if
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1975 @var{directory} is not absolute.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1976
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
1977 In the following example, suppose that @file{~rms/lewis} is the current
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
1978 default directory, and has five files whose names begin with @samp{f}:
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1979 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1980 @file{file.c.~2~}.@refill
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1981
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1982 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1983 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1984 (file-name-all-completions "f" "")
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
1985 @result{} ("foo" "file~" "file.c.~2~"
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1986 "file.c.~1~" "file.c")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1987 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1988
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1989 @group
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
1990 (file-name-all-completions "fo" "")
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1991 @result{} ("foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1992 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1993 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1994 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1995
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1996 @defun file-name-completion filename directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1997 This function completes the file name @var{filename} in directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1998 @var{directory}. It returns the longest prefix common to all file names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1999 in directory @var{directory} that start with @var{filename}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2000
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2001 If only one match exists and @var{filename} matches it exactly, the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2002 function returns @code{t}. The function returns @code{nil} if directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2003 @var{directory} contains no name starting with @var{filename}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2004
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2005 In the following example, suppose that the current default directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2006 has five files whose names begin with @samp{f}: @file{foo},
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2007 @file{file~}, @file{file.c}, @file{file.c.~1~}, and
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2008 @file{file.c.~2~}.@refill
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2009
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2010 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2011 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2012 (file-name-completion "fi" "")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2013 @result{} "file"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2014 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2015
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2016 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2017 (file-name-completion "file.c.~1" "")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2018 @result{} "file.c.~1~"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2019 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2020
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2021 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2022 (file-name-completion "file.c.~1~" "")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2023 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2024 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2025
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2026 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2027 (file-name-completion "file.c.~3" "")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2028 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2029 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2030 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2031 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2032
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2033 @defopt completion-ignored-extensions
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2034 @code{file-name-completion} usually ignores file names that end in any
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2035 string in this list. It does not ignore them when all the possible
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2036 completions end in one of these suffixes or when a buffer showing all
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2037 possible completions is displayed.@refill
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2038
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2039 A typical value might look like this:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2040
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2041 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2042 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2043 completion-ignored-extensions
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2044 @result{} (".o" ".elc" "~" ".dvi")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2045 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2046 @end example
39883
416c492df7c3 (File Name Completion): Document the significance of
Eli Zaretskii <eliz@gnu.org>
parents: 39296
diff changeset
2047
416c492df7c3 (File Name Completion): Document the significance of
Eli Zaretskii <eliz@gnu.org>
parents: 39296
diff changeset
2048 If an element of @code{completion-ignored-extensions} ends in a slash
416c492df7c3 (File Name Completion): Document the significance of
Eli Zaretskii <eliz@gnu.org>
parents: 39296
diff changeset
2049 @samp{/}, it signals a directory. The elements which do @emph{not} end
416c492df7c3 (File Name Completion): Document the significance of
Eli Zaretskii <eliz@gnu.org>
parents: 39296
diff changeset
2050 in a slash will never match a directory; thus, the above value will not
416c492df7c3 (File Name Completion): Document the significance of
Eli Zaretskii <eliz@gnu.org>
parents: 39296
diff changeset
2051 filter out a directory named @file{foo.elc}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2052 @end defopt
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2053
15765
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2054 @node Standard File Names
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2055 @subsection Standard File Names
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2056
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2057 Most of the file names used in Lisp programs are entered by the user.
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2058 But occasionally a Lisp program needs to specify a standard file name
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2059 for a particular use---typically, to hold customization information
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2060 about each user. For example, abbrev definitions are stored (by
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2061 default) in the file @file{~/.abbrev_defs}; the @code{completion}
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2062 package stores completions in the file @file{~/.completions}. These are
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2063 two of the many standard file names used by parts of Emacs for certain
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2064 purposes.
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2065
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2066 Various operating systems have their own conventions for valid file
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2067 names and for which file names to use for user profile data. A Lisp
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2068 program which reads a file using a standard file name ought to use, on
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2069 each type of system, a file name suitable for that system. The function
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2070 @code{convert-standard-filename} makes this easy to do.
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2071
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2072 @defun convert-standard-filename filename
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2073 This function alters the file name @var{filename} to fit the conventions
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2074 of the operating system in use, and returns the result as a new string.
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2075 @end defun
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2076
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2077 The recommended way to specify a standard file name in a Lisp program
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2078 is to choose a name which fits the conventions of GNU and Unix systems,
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2079 usually with a nondirectory part that starts with a period, and pass it
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2080 to @code{convert-standard-filename} instead of using it directly. Here
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2081 is an example from the @code{completion} package:
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2082
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2083 @example
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2084 (defvar save-completions-file-name
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2085 (convert-standard-filename "~/.completions")
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2086 "*The file name to save completions to.")
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2087 @end example
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2088
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2089 On GNU and Unix systems, and on some other systems as well,
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2090 @code{convert-standard-filename} returns its argument unchanged. On
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2091 some other systems, it alters the name to fit the system's conventions.
15765
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2092
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2093 For example, on MS-DOS the alterations made by this function include
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2094 converting a leading @samp{.} to @samp{_}, converting a @samp{_} in the
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2095 middle of the name to @samp{.} if there is no other @samp{.}, inserting
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2096 a @samp{.} after eight characters if there is none, and truncating to
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2097 three characters after the @samp{.}. (It makes other changes as well.)
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2098 Thus, @file{.abbrev_defs} becomes @file{_abbrev.def}, and
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2099 @file{.completions} becomes @file{_complet.ion}.
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2100
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2101 @node Contents of Directories
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2102 @section Contents of Directories
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2103 @cindex directory-oriented functions
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2104 @cindex file names in directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2105
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2106 A directory is a kind of file that contains other files entered under
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2107 various names. Directories are a feature of the file system.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2108
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2109 Emacs can list the names of the files in a directory as a Lisp list,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2110 or display the names in a buffer using the @code{ls} shell command. In
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2111 the latter case, it can optionally display information about each file,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2112 depending on the options passed to the @code{ls} command.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2113
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2114 @defun directory-files directory &optional full-name match-regexp nosort
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2115 This function returns a list of the names of the files in the directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2116 @var{directory}. By default, the list is in alphabetical order.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2117
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2118 If @var{full-name} is non-@code{nil}, the function returns the files'
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2119 absolute file names. Otherwise, it returns the names relative to
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2120 the specified directory.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2121
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2122 If @var{match-regexp} is non-@code{nil}, this function returns only
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2123 those file names that contain a match for that regular expression---the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2124 other file names are excluded from the list.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2125
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2126 @c Emacs 19 feature
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2127 If @var{nosort} is non-@code{nil}, @code{directory-files} does not sort
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2128 the list, so you get the file names in no particular order. Use this if
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2129 you want the utmost possible speed and don't care what order the files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2130 are processed in. If the order of processing is visible to the user,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2131 then the user will probably be happier if you do sort the names.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2132
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2133 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2134 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2135 (directory-files "~lewis")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2136 @result{} ("#foo#" "#foo.el#" "." ".."
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
2137 "dired-mods.el" "files.texi"
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2138 "files.texi.~1~")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2139 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2140 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2141
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2142 An error is signaled if @var{directory} is not the name of a directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2143 that can be read.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2144 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2145
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2146 @defun file-name-all-versions file dirname
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2147 This function returns a list of all versions of the file named
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2148 @var{file} in directory @var{dirname}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2149 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2150
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2151 @tindex file-expand-wildcards
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2152 @defun file-expand-wildcards pattern &optional full
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2153 This function expands the wildcard pattern @var{pattern}, returning
24952
a6db4671c7a0 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24951
diff changeset
2154 a list of file names that match it.
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2155
24952
a6db4671c7a0 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24951
diff changeset
2156 If @var{pattern} is written as an absolute file name,
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2157 the values are absolute also.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2158
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2159 If @var{pattern} is written as a relative file name, it is interpreted
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2160 relative to the current default directory. The file names returned are
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2161 normally also relative to the current default directory. However, if
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2162 @var{full} is non-@code{nil}, they are absolute.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2163 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2164
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2165 @defun insert-directory file switches &optional wildcard full-directory-p
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2166 This function inserts (in the current buffer) a directory listing for
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2167 directory @var{file}, formatted with @code{ls} according to
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2168 @var{switches}. It leaves point after the inserted text.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2169
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2170 The argument @var{file} may be either a directory name or a file
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2171 specification including wildcard characters. If @var{wildcard} is
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2172 non-@code{nil}, that means treat @var{file} as a file specification with
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2173 wildcards.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2174
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2175 If @var{full-directory-p} is non-@code{nil}, that means the directory
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2176 listing is expected to show the full contents of a directory. You
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2177 should specify @code{t} when @var{file} is a directory and switches do
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2178 not contain @samp{-d}. (The @samp{-d} option to @code{ls} says to
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2179 describe a directory itself as a file, rather than showing its
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2180 contents.)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2181
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2182 On most systems, this function works by running a directory listing
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2183 program whose name is in the variable @code{insert-directory-program}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2184 If @var{wildcard} is non-@code{nil}, it also runs the shell specified by
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2185 @code{shell-file-name}, to expand the wildcards.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2186
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2187 MS-DOS and MS-Windows systems usually lack the standard Unix program
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2188 @code{ls}, so this function emulates the standard Unix program @code{ls}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2189 with Lisp code.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2190 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2191
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2192 @defvar insert-directory-program
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2193 This variable's value is the program to run to generate a directory listing
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2194 for the function @code{insert-directory}. It is ignored on systems
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2195 which generate the listing with Lisp code.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2196 @end defvar
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2197
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2198 @node Create/Delete Dirs
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2199 @section Creating and Deleting Directories
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2200 @c Emacs 19 features
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2201
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2202 Most Emacs Lisp file-manipulation functions get errors when used on
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2203 files that are directories. For example, you cannot delete a directory
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2204 with @code{delete-file}. These special functions exist to create and
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2205 delete directories.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2206
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
2207 @defun make-directory dirname &optional parents
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2208 This function creates a directory named @var{dirname}.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
2209 If @var{parents} is non-@code{nil}, that means to create
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
2210 the parent directories first, if they don't already exist.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2211 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2212
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2213 @defun delete-directory dirname
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2214 This function deletes the directory named @var{dirname}. The function
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2215 @code{delete-file} does not work for files that are directories; you
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2216 must use @code{delete-directory} for them. If the directory contains
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2217 any files, @code{delete-directory} signals an error.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2218 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2219
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2220 @node Magic File Names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2221 @section Making Certain File Names ``Magic''
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2222 @cindex magic file names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2223
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2224 @c Emacs 19 feature
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2225 You can implement special handling for certain file names. This is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2226 called making those names @dfn{magic}. The principal use for this
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2227 feature is in implementing remote file names (@pxref{Remote Files,,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2228 Remote Files, emacs, The GNU Emacs Manual}).
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2229
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2230 To define a kind of magic file name, you must supply a regular
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2231 expression to define the class of names (all those that match the
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2232 regular expression), plus a handler that implements all the primitive
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2233 Emacs file operations for file names that do match.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2234
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2235 The variable @code{file-name-handler-alist} holds a list of handlers,
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2236 together with regular expressions that determine when to apply each
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2237 handler. Each element has this form:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2238
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2239 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2240 (@var{regexp} . @var{handler})
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2241 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2242
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2243 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2244 All the Emacs primitives for file access and file name transformation
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2245 check the given file name against @code{file-name-handler-alist}. If
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2246 the file name matches @var{regexp}, the primitives handle that file by
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2247 calling @var{handler}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2248
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2249 The first argument given to @var{handler} is the name of the primitive;
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2250 the remaining arguments are the arguments that were passed to that
37582
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2251 primitive. (The first of these arguments is most often the file name
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2252 itself.) For example, if you do this:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2253
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2254 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2255 (file-exists-p @var{filename})
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2256 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2257
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2258 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2259 and @var{filename} has handler @var{handler}, then @var{handler} is
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2260 called like this:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2261
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2262 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2263 (funcall @var{handler} 'file-exists-p @var{filename})
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2264 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2265
37582
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2266 When a function takes two or more arguments that must be file names,
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2267 it checks each of those names for a handler. For example, if you do
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2268 this:
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2269
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2270 @example
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2271 (expand-file-name @var{filename} @var{dirname})
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2272 @end example
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2273
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2274 @noindent
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2275 then it checks for a handler for @var{filename} and then for a handler
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2276 for @var{dirname}. In either case, the @var{handler} is called like
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2277 this:
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2278
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2279 @example
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2280 (funcall @var{handler} 'expand-file-name @var{filename} @var{dirname})
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2281 @end example
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2282
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2283 @noindent
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2284 The @var{handler} then needs to figure out whether to handle
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2285 @var{filename} or @var{dirname}.
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2286
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2287 Here are the operations that a magic file name handler gets to handle:
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2288
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
2289 @ifnottex
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2290 @noindent
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2291 @code{access-file}, @code{add-name-to-file},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2292 @code{byte-compiler-base-file-name},@*
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2293 @code{copy-file}, @code{delete-directory},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2294 @code{delete-file},
12226
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2295 @code{diff-latest-backup-file},
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2296 @code{directory-file-name},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2297 @code{directory-files},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2298 @code{directory-files-and-attributes},
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
2299 @code{dired-call-process},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2300 @code{dired-compress-file}, @code{dired-uncache},@*
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2301 @code{expand-file-name},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2302 @code{file-accessible-directory-p},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2303 @code{file-attributes},
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2304 @code{file-directory-p},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2305 @code{file-executable-p}, @code{file-exists-p},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2306 @code{file-local-copy},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2307 @code{file-modes}, @code{file-name-all-completions},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2308 @code{file-name-as-directory},
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2309 @code{file-name-completion},
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
2310 @code{file-name-directory},
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
2311 @code{file-name-nondirectory},
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2312 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
15765
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2313 @code{file-ownership-preserved-p},
11626
0b86aef0c387 Mention file-regular-p operation.
Richard M. Stallman <rms@gnu.org>
parents: 8364
diff changeset
2314 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
12226
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2315 @code{file-truename}, @code{file-writable-p},
15765
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2316 @code{find-backup-file-name},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2317 @code{find-file-noselect},@*
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2318 @code{get-file-buffer},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2319 @code{insert-directory},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2320 @code{insert-file-contents},@*
15765
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2321 @code{load}, @code{make-directory},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2322 @code{make-directory-internal},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2323 @code{make-symbolic-link},@*
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2324 @code{rename-file}, @code{set-file-modes},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2325 @code{set-visited-file-modtime}, @code{shell-command},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2326 @code{substitute-in-file-name},@*
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2327 @code{unhandled-file-name-directory},
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
2328 @code{vc-registered},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2329 @code{verify-visited-file-modtime},@*
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2330 @code{write-region}.
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
2331 @end ifnottex
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2332 @iftex
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2333 @noindent
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2334 @flushleft
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2335 @code{access-file}, @code{add-name-to-file},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2336 @code{byte-com@discretionary{}{}{}piler-base-file-name},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2337 @code{copy-file}, @code{delete-directory},
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2338 @code{delete-file},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2339 @code{diff-latest-backup-file},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2340 @code{directory-file-name},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2341 @code{directory-files},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2342 @code{directory-files-and-at@discretionary{}{}{}tributes},
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2343 @code{dired-call-process},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2344 @code{dired-compress-file}, @code{dired-uncache},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2345 @code{expand-file-name},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2346 @code{file-accessible-direc@discretionary{}{}{}tory-p},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2347 @code{file-attributes},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2348 @code{file-direct@discretionary{}{}{}ory-p},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2349 @code{file-executable-p}, @code{file-exists-p},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2350 @code{file-local-copy},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2351 @code{file-modes}, @code{file-name-all-completions},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2352 @code{file-name-as-directory},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2353 @code{file-name-completion},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2354 @code{file-name-directory},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2355 @code{file-name-nondirec@discretionary{}{}{}tory},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2356 @code{file-name-sans-versions}, @code{file-newer-than-file-p},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2357 @code{file-ownership-pre@discretionary{}{}{}served-p},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2358 @code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2359 @code{file-truename}, @code{file-writable-p},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2360 @code{find-backup-file-name},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2361 @code{find-file-noselect},
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2362 @code{get-file-buffer},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2363 @code{insert-directory},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2364 @code{insert-file-contents},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2365 @code{load}, @code{make-direc@discretionary{}{}{}tory},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2366 @code{make-direc@discretionary{}{}{}tory-internal},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2367 @code{make-symbolic-link},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2368 @code{rename-file}, @code{set-file-modes},
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2369 @code{set-visited-file-modtime}, @code{shell-command},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2370 @code{substitute-in-file-name},
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2371 @code{unhandled-file-name-directory},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2372 @code{vc-regis@discretionary{}{}{}tered},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2373 @code{verify-visited-file-modtime},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2374 @code{write-region}.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2375 @end flushleft
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2376 @end iftex
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2377
8118
56b5ed321f8d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2378 Handlers for @code{insert-file-contents} typically need to clear the
56b5ed321f8d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2379 buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
56b5ed321f8d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2380 @var{visit} argument is non-@code{nil}. This also has the effect of
56b5ed321f8d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2381 unlocking the buffer if it is locked.
56b5ed321f8d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2382
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2383 The handler function must handle all of the above operations, and
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2384 possibly others to be added in the future. It need not implement all
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2385 these operations itself---when it has nothing special to do for a
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2386 certain operation, it can reinvoke the primitive, to handle the
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2387 operation ``in the usual way''. It should always reinvoke the primitive
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2388 for an operation it does not recognize. Here's one way to do this:
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2389
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2390 @smallexample
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2391 (defun my-file-handler (operation &rest args)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2392 ;; @r{First check for the specific operations}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2393 ;; @r{that we have special handling for.}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2394 (cond ((eq operation 'insert-file-contents) @dots{})
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2395 ((eq operation 'write-region) @dots{})
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2396 @dots{}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2397 ;; @r{Handle any operation we don't know about.}
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2398 (t (let ((inhibit-file-name-handlers
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
2399 (cons 'my-file-handler
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2400 (and (eq inhibit-file-name-operation operation)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2401 inhibit-file-name-handlers)))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2402 (inhibit-file-name-operation operation))
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2403 (apply operation args)))))
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2404 @end smallexample
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2405
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2406 When a handler function decides to call the ordinary Emacs primitive for
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2407 the operation at hand, it needs to prevent the primitive from calling
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2408 the same handler once again, thus leading to an infinite recursion. The
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2409 example above shows how to do this, with the variables
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2410 @code{inhibit-file-name-handlers} and
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2411 @code{inhibit-file-name-operation}. Be careful to use them exactly as
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2412 shown above; the details are crucial for proper behavior in the case of
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2413 multiple handlers, and for operations that have two file names that may
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2414 each have handlers.
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2415
51020
417a9e80f335 (Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents: 50501
diff changeset
2416 @kindex safe-magic (@r{property})
417a9e80f335 (Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents: 50501
diff changeset
2417 Handlers that don't really do anything specal for actual access to the
417a9e80f335 (Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents: 50501
diff changeset
2418 file---such as the ones that implement completion of host names for
417a9e80f335 (Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents: 50501
diff changeset
2419 remote file names---should have a non-@code{nil} @code{safe-magic}
417a9e80f335 (Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents: 50501
diff changeset
2420 property. For instance, Emacs normally ``protects'' directory names
417a9e80f335 (Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents: 50501
diff changeset
2421 it finds in @code{PATH} from becoming magic, if they look like magic
417a9e80f335 (Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents: 50501
diff changeset
2422 file names, by prefixing them with @samp{/:}. But if the handler that
417a9e80f335 (Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents: 50501
diff changeset
2423 would be used for them has a non-@code{nil} @code{safe-magic}
417a9e80f335 (Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents: 50501
diff changeset
2424 property, the @samp{/:} is not added.
417a9e80f335 (Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents: 50501
diff changeset
2425
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2426 @defvar inhibit-file-name-handlers
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2427 This variable holds a list of handlers whose use is presently inhibited
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2428 for a certain operation.
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2429 @end defvar
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2430
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2431 @defvar inhibit-file-name-operation
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2432 The operation for which certain handlers are presently inhibited.
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2433 @end defvar
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2434
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2435 @defun find-file-name-handler file operation
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2436 This function returns the handler function for file name @var{file}, or
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2437 @code{nil} if there is none. The argument @var{operation} should be the
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2438 operation to be performed on the file---the value you will pass to the
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2439 handler as its first argument when you call it. The operation is needed
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2440 for comparison with @code{inhibit-file-name-operation}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2441 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2442
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2443 @defun file-local-copy filename
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2444 This function copies file @var{filename} to an ordinary non-magic file,
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2445 if it isn't one already.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2446
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2447 If @var{filename} specifies a magic file name, which programs
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2448 outside Emacs cannot directly read or write, this copies the contents to
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2449 an ordinary file and returns that file's name.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2450
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2451 If @var{filename} is an ordinary file name, not magic, then this function
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2452 does nothing and returns @code{nil}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2453 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2454
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2455 @defun unhandled-file-name-directory filename
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2456 This function returns the name of a directory that is not magic. It
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2457 uses the directory part of @var{filename} if that is not magic. For a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2458 magic file name, it invokes the file name handler, which therefore
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2459 decides what value to return.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2460
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2461 This is useful for running a subprocess; every subprocess must have a
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2462 non-magic directory to serve as its current directory, and this function
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2463 is a good way to come up with one.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2464 @end defun
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2465
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2466 @node Format Conversion
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2467 @section File Format Conversion
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2468
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2469 @cindex file format conversion
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2470 @cindex encoding file formats
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2471 @cindex decoding file formats
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2472 The variable @code{format-alist} defines a list of @dfn{file formats},
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2473 which describe textual representations used in files for the data (text,
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2474 text-properties, and possibly other information) in an Emacs buffer.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2475 Emacs performs format conversion if appropriate when reading and writing
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2476 files.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2477
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2478 @defvar format-alist
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2479 This list contains one format definition for each defined file format.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2480 @end defvar
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2481
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2482 @cindex format definition
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2483 Each format definition is a list of this form:
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2484
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2485 @example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2486 (@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2487 @end example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2488
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2489 Here is what the elements in a format definition mean:
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2490
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2491 @table @var
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2492 @item name
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2493 The name of this format.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2494
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2495 @item doc-string
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2496 A documentation string for the format.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2497
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2498 @item regexp
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2499 A regular expression which is used to recognize files represented in
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2500 this format.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2501
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2502 @item from-fn
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2503 A shell command or function to decode data in this format (to convert
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2504 file data into the usual Emacs data representation).
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2505
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2506 A shell command is represented as a string; Emacs runs the command as a
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2507 filter to perform the conversion.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2508
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2509 If @var{from-fn} is a function, it is called with two arguments, @var{begin}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2510 and @var{end}, which specify the part of the buffer it should convert.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2511 It should convert the text by editing it in place. Since this can
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2512 change the length of the text, @var{from-fn} should return the modified
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2513 end position.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2514
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2515 One responsibility of @var{from-fn} is to make sure that the beginning
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2516 of the file no longer matches @var{regexp}. Otherwise it is likely to
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2517 get called again.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2518
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2519 @item to-fn
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2520 A shell command or function to encode data in this format---that is, to
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2521 convert the usual Emacs data representation into this format.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2522
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2523 If @var{to-fn} is a string, it is a shell command; Emacs runs the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2524 command as a filter to perform the conversion.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2525
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2526 If @var{to-fn} is a function, it is called with two arguments, @var{begin}
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2527 and @var{end}, which specify the part of the buffer it should convert.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2528 There are two ways it can do the conversion:
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2529
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2530 @itemize @bullet
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2531 @item
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2532 By editing the buffer in place. In this case, @var{to-fn} should
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2533 return the end-position of the range of text, as modified.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2534
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2535 @item
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2536 By returning a list of annotations. This is a list of elements of the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2537 form @code{(@var{position} . @var{string})}, where @var{position} is an
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2538 integer specifying the relative position in the text to be written, and
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2539 @var{string} is the annotation to add there. The list must be sorted in
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2540 order of position when @var{to-fn} returns it.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2541
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2542 When @code{write-region} actually writes the text from the buffer to the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2543 file, it intermixes the specified annotations at the corresponding
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2544 positions. All this takes place without modifying the buffer.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2545 @end itemize
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2546
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2547 @item modify
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2548 A flag, @code{t} if the encoding function modifies the buffer, and
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2549 @code{nil} if it works by returning a list of annotations.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2550
27259
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
2551 @item mode-fn
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
2552 A minor-mode function to call after visiting a file converted from this
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
2553 format. The function is called with one argument, the integer 1;
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
2554 that tells a minor-mode function to enable the mode.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2555 @end table
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2556
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2557 The function @code{insert-file-contents} automatically recognizes file
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2558 formats when it reads the specified file. It checks the text of the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2559 beginning of the file against the regular expressions of the format
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2560 definitions, and if it finds a match, it calls the decoding function for
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2561 that format. Then it checks all the known formats over again.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2562 It keeps checking them until none of them is applicable.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2563
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2564 Visiting a file, with @code{find-file-noselect} or the commands that use
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2565 it, performs conversion likewise (because it calls
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2566 @code{insert-file-contents}); it also calls the mode function for each
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2567 format that it decodes. It stores a list of the format names in the
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2568 buffer-local variable @code{buffer-file-format}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2569
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2570 @defvar buffer-file-format
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2571 This variable states the format of the visited file. More precisely,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2572 this is a list of the file format names that were decoded in the course
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2573 of visiting the current buffer's file. It is always buffer-local in all
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2574 buffers.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2575 @end defvar
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2576
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2577 When @code{write-region} writes data into a file, it first calls the
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2578 encoding functions for the formats listed in @code{buffer-file-format},
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2579 in the order of appearance in the list.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2580
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2581 @deffn Command format-write-file file format
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2582 This command writes the current buffer contents into the file @var{file}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2583 in format @var{format}, and makes that format the default for future
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2584 saves of the buffer. The argument @var{format} is a list of format
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2585 names.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2586 @end deffn
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2587
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2588 @deffn Command format-find-file file format
12226
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2589 This command finds the file @var{file}, converting it according to
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2590 format @var{format}. It also makes @var{format} the default if the
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2591 buffer is saved later.
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2592
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2593 The argument @var{format} is a list of format names. If @var{format} is
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2594 @code{nil}, no conversion takes place. Interactively, typing just
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2595 @key{RET} for @var{format} specifies @code{nil}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2596 @end deffn
12226
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2597
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2598 @deffn Command format-insert-file file format &optional beg end
12226
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2599 This command inserts the contents of file @var{file}, converting it
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2600 according to format @var{format}. If @var{beg} and @var{end} are
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2601 non-@code{nil}, they specify which part of the file to read, as in
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2602 @code{insert-file-contents} (@pxref{Reading from Files}).
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2603
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2604 The return value is like what @code{insert-file-contents} returns: a
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2605 list of the absolute file name and the length of the data inserted
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2606 (after conversion).
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2607
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2608 The argument @var{format} is a list of format names. If @var{format} is
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2609 @code{nil}, no conversion takes place. Interactively, typing just
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2610 @key{RET} for @var{format} specifies @code{nil}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2611 @end deffn
12226
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2612
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2613 @defvar auto-save-file-format
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2614 This variable specifies the format to use for auto-saving. Its value is
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2615 a list of format names, just like the value of
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2616 @code{buffer-file-format}; however, it is used instead of
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2617 @code{buffer-file-format} for writing auto-save files. This variable is
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2618 always buffer-local in all buffers.
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2619 @end defvar