annotate lispref/files.texi @ 77361:916f8aa2138d

(File Name Expansion): Clarify previous change.
author Richard M. Stallman <rms@gnu.org>
date Sat, 21 Apr 2007 08:58:15 +0000
parents 95a196e2e465
children cf24d1dc433c 6b44d05a5f0b e6fdae9180d4
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.
75250
6d19c76d81c5 Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents: 74688
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
6d19c76d81c5 Update copyright for years from Emacs 21 to present (mainly adding
Glenn Morris <rgm@gnu.org>
parents: 74688
diff changeset
4 @c 2002, 2003, 2004, 2005, 2006, 2007 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
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
98 Aside from some technical details, the body of the @code{find-file}
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
99 function is basically equivalent to:
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 62856
diff changeset
101 @smallexample
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
102 (switch-to-buffer (find-file-noselect filename nil nil wildcards))
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 62856
diff changeset
103 @end smallexample
6555
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
70657
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
117 This function is the guts of all the file-visiting functions. It
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
118 returns a buffer visiting the file @var{filename}. You may make the
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
119 buffer current or display it in a window if you wish, but this
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
120 function does not do so.
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
121
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
122 The function returns an existing buffer if there is one; otherwise it
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
123 creates a new buffer and reads the file into it. When
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
124 @code{find-file-noselect} uses an existing buffer, it first verifies
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
125 that the file has not changed since it was last visited or saved in
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
126 that buffer. If the file has changed, this function asks the user
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
127 whether to reread the changed file. If the user says @samp{yes}, any
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
128 edits previously made in the buffer are lost.
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
129
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
130 Reading the file involves decoding the file's contents (@pxref{Coding
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
131 Systems}), including end-of-line conversion, and format conversion
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
132 (@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil},
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
133 then @code{find-file-noselect} expands wildcard characters in
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
134 @var{filename} and visits all the matching files.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
136 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
137 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
138 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
139 @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
140 area, and leaves the buffer empty.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
141
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
142 The @code{find-file-noselect} function normally calls
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
143 @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
144 Visiting}). That function sets the buffer major mode, parses local
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
145 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
146 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
147 @code{find-file-hook}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
148
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
149 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
150 @code{after-find-file} is not called, and the
70657
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
151 @code{find-file-not-found-functions} are not run in case of failure.
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
152 What's more, a non-@code{nil} @var{rawfile} value suppresses coding
9a270d0b2af7 (Visiting Functions): Rewrite in find-file-noselect.
Richard M. Stallman <rms@gnu.org>
parents: 70624
diff changeset
153 system conversion and format conversion.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154
32842
b10fc3a9befa (Visiting Functions): Return value of find-file-noselect may be a list
Kenichi Handa <handa@m17n.org>
parents: 30501
diff changeset
155 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
156 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
157 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
158 various files.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 (find-file-noselect "/etc/fstab")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 @result{} #<buffer fstab>
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
165 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
166 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
167
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
168 @deffn Command find-file-other-window filename &optional wildcards
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
169 This command selects a buffer visiting the file @var{filename}, but
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
170 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
171 existing window or split a window; see @ref{Displaying Buffers}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
172
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
173 When this command is called interactively, it prompts for
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
174 @var{filename}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
175 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
176
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
177 @deffn Command find-file-read-only filename &optional wildcards
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
178 This command selects a buffer visiting the file @var{filename}, like
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
179 @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
180 Buffers}, for related functions and variables.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
181
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
182 When this command is called interactively, it prompts for
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
183 @var{filename}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
184 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
185
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
186 @deffn Command view-file filename
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
187 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
188 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
189 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
190 modify the text. Entering View mode runs the normal hook
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
191 @code{view-mode-hook}. @xref{Hooks}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
192
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
193 When @code{view-file} is called interactively, it prompts for
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
194 @var{filename}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
195 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
196
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
197 @defopt find-file-wildcards
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
198 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
199 commands check for wildcard characters and visit all the files that
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
200 match them (when invoked interactively or when their @var{wildcards}
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
201 argument is non-@code{nil}). If this option is @code{nil}, then
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
202 the @code{find-file} commands ignore their @var{wildcards} argument
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
203 and never treat wildcard characters specially.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
204 @end defopt
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
205
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
206 @defvar find-file-hook
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
207 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
208 file is visited. The file's local-variables specification (if any) will
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
209 have been processed before the hooks are run. The buffer visiting the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
210 file is current when the hook functions are run.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
211
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
212 This variable is a normal hook. @xref{Hooks}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 @end defvar
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
215 @defvar find-file-not-found-functions
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216 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
217 @code{find-file} or @code{find-file-noselect} is passed a nonexistent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 file name. @code{find-file-noselect} calls these functions as soon as
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 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
220 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
221 already set up.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
222
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
223 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
224 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
225 @end defvar
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
226
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
227 @node Subroutines of Visiting
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
228 @comment node-name, next, previous, up
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
229 @subsection Subroutines of Visiting
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
230
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
231 The @code{find-file-noselect} function uses two important subroutines
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
232 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
233 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
234
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
235 @defun create-file-buffer filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 This function creates a suitably named buffer for visiting
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237 @var{filename}, and returns it. It uses @var{filename} (sans directory)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238 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
239 @samp{<2>} to get an unused name. See also @ref{Creating Buffers}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
241 @strong{Please note:} @code{create-file-buffer} does @emph{not}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
242 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
243 It also does not use the default major mode.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
244
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
245 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
246 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
247 (create-file-buffer "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
248 @result{} #<buffer foo>
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
249 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
250 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
251 (create-file-buffer "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252 @result{} #<buffer foo<2>>
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
253 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 (create-file-buffer "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
256 @result{} #<buffer foo<3>>
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
257 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
259
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
260 This function is used by @code{find-file-noselect}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
264 @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
265 This function sets the buffer major mode, and parses local variables
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 (@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
267 and by the default revert function (@pxref{Reverting}).
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
268
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
269 @cindex new file message
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
270 @cindex file open error
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
271 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
272 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
273 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
274 @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
275 call @code{after-find-file}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
276
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
277 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
278 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
279
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
280 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
281 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
282
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
283 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
284 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
285 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
286 of this variable.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
287
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
288 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
289 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
290 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
291 @code{revert-buffer} in some cases.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
292
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
293 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
294 in the list @code{find-file-hook}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
295 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 @node Saving Buffers
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
298 @section Saving Buffers
76841
fc9d442f98d2 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 75476
diff changeset
299 @cindex saving buffers
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
301 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
302 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
303 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
304 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
305 means copying the contents of the buffer into the file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
306
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
307 @deffn Command save-buffer &optional backup-option
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 This function saves the contents of the current buffer in its visited
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
309 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
310 Otherwise it does nothing.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
312 @code{save-buffer} is responsible for making backup files. Normally,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
313 @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
314 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
315 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
316 other circumstances:
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
317
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
318 @itemize @bullet
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
319 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
320 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
321 @code{save-buffer} function marks this version of the file to be
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
322 backed up when the buffer is next saved.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
323
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
324 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 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
326 @code{save-buffer} function unconditionally backs up the previous
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
327 version of the file before saving it.
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
328
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
329 @item
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
330 With an argument of 0, unconditionally do @emph{not} make any backup file.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
331 @end itemize
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
333
56215
c9aa4127a482 Reposition @anchor's.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56207
diff changeset
334 @deffn Command save-some-buffers &optional save-silently-p pred
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
335 @anchor{Definition of save-some-buffers}
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336 This command saves some modified file-visiting buffers. Normally it
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
337 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
338 non-@code{nil}, it saves all the file-visiting buffers without querying
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
339 the user.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
340
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
341 The optional @var{pred} argument controls which buffers to ask about
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
342 (or to save silently if @var{save-silently-p} is non-@code{nil}).
26770
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
343 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
344 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
345 buffers---those that have a non-@code{nil} buffer-local value of
65369
822218f80ae4 2005-09-08 Chong Yidong <cyd@stupidchicken.com>
Chong Yidong <cyd@stupidchicken.com>
parents: 65248
diff changeset
346 @code{buffer-offer-save} (@pxref{Killing Buffers}). A user who says
822218f80ae4 2005-09-08 Chong Yidong <cyd@stupidchicken.com>
Chong Yidong <cyd@stupidchicken.com>
parents: 65248
diff changeset
347 @samp{yes} to saving a non-file buffer is asked to specify the file
65437
035ea9e34f56 2005-09-10 Chong Yidong <cyd@stupidchicken.com>
Chong Yidong <cyd@stupidchicken.com>
parents: 65369
diff changeset
348 name to use. The @code{save-buffers-kill-emacs} function passes the
65369
822218f80ae4 2005-09-08 Chong Yidong <cyd@stupidchicken.com>
Chong Yidong <cyd@stupidchicken.com>
parents: 65248
diff changeset
349 value @code{t} for @var{pred}.
26770
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
350
2d8554ed8748 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26696
diff changeset
351 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
352 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
353 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
354 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
355 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
356
56215
c9aa4127a482 Reposition @anchor's.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56207
diff changeset
357 @deffn Command write-file filename &optional confirm
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
358 @anchor{Definition of write-file}
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
359 This function writes the current buffer into file @var{filename}, makes
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
360 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
361 the buffer based on @var{filename}, appending a string like @samp{<2>}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362 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
363 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
364 @code{save-buffer}.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
365
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
366 If @var{confirm} is non-@code{nil}, that means to ask for confirmation
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
367 before overwriting an existing file. Interactively, confirmation is
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
368 required, unless the user supplies a prefix argument.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
369
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
370 If @var{filename} is an existing directory, or a symbolic link to one,
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
371 @code{write-file} uses the name of the visited file, in directory
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
372 @var{filename}. If the buffer is not visiting a file, it uses the
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
373 buffer name instead.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
374 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
375
15913
f415fdc67ad3 Add xrefs from Saving Buffers to Format Conversion and Saving
Richard M. Stallman <rms@gnu.org>
parents: 15765
diff changeset
376 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
377 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
378 ``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
379
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
380 @defvar write-file-functions
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
381 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
382 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
383 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
384 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
385 executed.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
386
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
387 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
388 is responsible for making a backup file (if that is appropriate).
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
389 To do so, execute the following code:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
390
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
391 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
392 (or buffer-backed-up (backup-buffer))
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
393 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
394
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
395 You might wish to save the file modes value returned by
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
396 @code{backup-buffer} and use that (if non-@code{nil}) to set the mode
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
397 bits of the file that you write. This is what @code{save-buffer}
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
398 normally does. @xref{Making Backups,, Making Backup Files}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
399
70624
97f1ae99fe30 (Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents: 70538
diff changeset
400 The hook functions in @code{write-file-functions} are also responsible
97f1ae99fe30 (Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents: 70538
diff changeset
401 for encoding the data (if desired): they must choose a suitable coding
97f1ae99fe30 (Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents: 70538
diff changeset
402 system and end-of-line conversion (@pxref{Lisp and Coding Systems}),
97f1ae99fe30 (Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents: 70538
diff changeset
403 perform the encoding (@pxref{Explicit Encoding}), and set
97f1ae99fe30 (Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents: 70538
diff changeset
404 @code{last-coding-system-used} to the coding system that was used
97f1ae99fe30 (Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents: 70538
diff changeset
405 (@pxref{Encoding and I/O}).
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
406
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
407 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
408 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
409 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
410 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
411 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
412 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
413 @code{write-contents-functions} instead.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
414
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 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
416 @code{remove-hook} to manipulate the list. @xref{Hooks}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
417 @end defvar
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
418
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
419 @c Emacs 19 feature
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
420 @defvar write-contents-functions
56322
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
421 This works just like @code{write-file-functions}, but it is intended
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
422 for hooks that pertain to the buffer's contents, not to the particular
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
423 visited file or its location. Such hooks are usually set up by major
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
424 modes, as buffer-local bindings for this variable. This variable
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
425 automatically becomes buffer-local whenever it is set; switching to a
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
426 new major mode always resets this variable, but calling
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
427 @code{set-visited-file-name} does not.
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
428
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
429 If any of the functions in this hook returns non-@code{nil}, the file
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
430 is considered already written and the rest are not called and neither
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
431 are the functions in @code{write-file-functions}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
432 @end defvar
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
433
53531
5bd5de5e98c2 (Saving Buffers): Clarify descriptions of `write-contents-functions'
Luc Teirlinck <teirllm@auburn.edu>
parents: 53505
diff changeset
434 @defopt before-save-hook
5bd5de5e98c2 (Saving Buffers): Clarify descriptions of `write-contents-functions'
Luc Teirlinck <teirllm@auburn.edu>
parents: 53505
diff changeset
435 This normal hook runs before a buffer is saved in its visited file,
5bd5de5e98c2 (Saving Buffers): Clarify descriptions of `write-contents-functions'
Luc Teirlinck <teirllm@auburn.edu>
parents: 53505
diff changeset
436 regardless of whether that is done normally or by one of the hooks
53575
a679a0134e06 *** empty log message ***
Luc Teirlinck <teirllm@auburn.edu>
parents: 53531
diff changeset
437 described above. For instance, the @file{copyright.el} program uses
a679a0134e06 *** empty log message ***
Luc Teirlinck <teirllm@auburn.edu>
parents: 53531
diff changeset
438 this hook to make sure the file you are saving has the current year in
a679a0134e06 *** empty log message ***
Luc Teirlinck <teirllm@auburn.edu>
parents: 53531
diff changeset
439 its copyright notice.
53531
5bd5de5e98c2 (Saving Buffers): Clarify descriptions of `write-contents-functions'
Luc Teirlinck <teirllm@auburn.edu>
parents: 53505
diff changeset
440 @end defopt
53505
780b9eb8b58e hooks.texi (Standard Hooks): Add before-save-hook.
Simon Josefsson <jas@extundo.com>
parents: 53425
diff changeset
441
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
442 @c Emacs 19 feature
53531
5bd5de5e98c2 (Saving Buffers): Clarify descriptions of `write-contents-functions'
Luc Teirlinck <teirllm@auburn.edu>
parents: 53505
diff changeset
443 @defopt after-save-hook
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 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
445 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
446 highlighting information in a cache file.
53531
5bd5de5e98c2 (Saving Buffers): Clarify descriptions of `write-contents-functions'
Luc Teirlinck <teirllm@auburn.edu>
parents: 53505
diff changeset
447 @end defopt
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
448
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
449 @defopt file-precious-flag
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
450 If this variable is non-@code{nil}, then @code{save-buffer} protects
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
451 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
452 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
453 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
454 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
455 invalid file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
456
12226
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
457 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
458 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
459 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
460
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
461 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
462 in particular buffers.
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
463 @end defopt
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 @defopt require-final-newline
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 This variable determines whether files may be written out that do
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 @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
468 @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
469 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
470 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
471 @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
472 case arises.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
474 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
475 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
476 major modes set it to @code{t} in particular buffers.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 @end defopt
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
478
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
479 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
480 Name}).
15765
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
481
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
482 @node Reading from Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
483 @comment node-name, next, previous, up
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
484 @section Reading from Files
76841
fc9d442f98d2 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 75476
diff changeset
485 @cindex reading from files
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
486
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
487 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
488 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
489 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
490
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
491 @defun insert-file-contents filename &optional visit beg end replace
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
492 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
493 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
494 and the length of the data inserted. An error is signaled if
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
495 @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
496
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
497 The function @code{insert-file-contents} checks the file contents
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
498 against the defined file formats, and converts the file contents if
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
499 appropriate. @xref{Format Conversion}. It also calls the functions in
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
500 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
501 Properties}. Normally, one of the functions in the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
502 @code{after-insert-file-functions} list determines the coding system
70624
97f1ae99fe30 (Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents: 70538
diff changeset
503 (@pxref{Coding Systems}) used for decoding the file's contents,
97f1ae99fe30 (Visiting Functions, Reading from Files, Saving Buffers): Mention code and EOL
Eli Zaretskii <eliz@gnu.org>
parents: 70538
diff changeset
504 including end-of-line conversion.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
505
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
506 If @var{visit} is non-@code{nil}, this function additionally marks the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
507 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
508 is visiting the file @var{filename}: these include the buffer's visited
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
509 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
510 @code{find-file-noselect} and you probably should not use it yourself.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
511
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
512 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
513 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
514 must be @code{nil}. For example,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
515
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
516 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
517 (insert-file-contents filename nil 0 500)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
518 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
519
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
520 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
521 inserts the first 500 characters of a file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
522
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
523 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
524 contents of the buffer (actually, just the accessible portion) with the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
525 contents of the file. This is better than simply deleting the buffer
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
526 contents and inserting the whole file, because (1) it preserves some
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
527 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
528
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
529 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
530 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
531 @var{visit} are @code{nil}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
532 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
533
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
534 @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
535 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
536 not do format decoding (@pxref{Format Conversion}), does not do
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
537 character code conversion (@pxref{Coding Systems}), does not run
45979
87962bf716e3 *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 40188
diff changeset
538 @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
539 on.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
540 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
541
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
542 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
543 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
544 @ref{Magic File Names}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
545
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
546 @node Writing to Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
547 @comment node-name, next, previous, up
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
548 @section Writing to Files
76841
fc9d442f98d2 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 75476
diff changeset
549 @cindex writing to files
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
550
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
551 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
552 to a file on disk using the @code{append-to-file} and
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
553 @code{write-region} functions. Don't use these functions to write to
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
554 files that are being visited; that could cause confusion in the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
555 mechanisms for visiting.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
556
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
557 @deffn Command append-to-file start end filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
558 This function appends the contents of the region delimited by
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
559 @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
560 @var{filename}. If that file does not exist, it is created. This
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
561 function returns @code{nil}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
562
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
563 An error is signaled if @var{filename} specifies a nonwritable file,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
564 or a nonexistent file in a directory where files cannot be created.
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
565
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
566 When called from Lisp, this function is completely equivalent to:
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
567
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
568 @example
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
569 (write-region start end filename t)
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
570 @end example
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
571 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
572
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
573 @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
574 This function writes the region delimited by @var{start} and @var{end}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 in the current buffer into the file specified by @var{filename}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
577 If @var{start} is @code{nil}, then the command writes the entire buffer
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
578 contents (@emph{not} just the accessible portion) to the file and
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
579 ignores @var{end}.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
580
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 @c Emacs 19 feature
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582 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
583 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
584 this case.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 If @var{append} is non-@code{nil}, then the specified text is appended
60444
78a2cd972ba1 (Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 59877
diff changeset
587 to the existing file contents (if any). If @var{append} is an
78a2cd972ba1 (Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 59877
diff changeset
588 integer, @code{write-region} seeks to that byte offset from the start
78a2cd972ba1 (Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 59877
diff changeset
589 of the file and writes the data from there.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
590
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
591 If @var{mustbenew} is non-@code{nil}, then @code{write-region} asks
60444
78a2cd972ba1 (Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 59877
diff changeset
592 for confirmation if @var{filename} names an existing file. If
78a2cd972ba1 (Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 59877
diff changeset
593 @var{mustbenew} is the symbol @code{excl}, then @code{write-region}
78a2cd972ba1 (Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 59877
diff changeset
594 does not ask for confirmation, but instead it signals an error
78a2cd972ba1 (Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 59877
diff changeset
595 @code{file-already-exists} if the file already exists.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
596
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
597 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
598 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
599 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
600 before Emacs does, without Emacs's noticing.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
601
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
602 If @var{visit} is @code{t}, then Emacs establishes an association
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
603 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
604 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
605 @var{filename}'s modtime, and marks the buffer as not modified. This
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
606 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
607 it yourself.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
608
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
609 @c Emacs 19 feature
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
610 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
611 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
612 the buffer as visiting another file (@var{visit}). The argument
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 @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
614 @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
615 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
616 really know what you're doing.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
618 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
619 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
620 @var{filename} and @var{visit} for that purpose.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
621
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
622 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
623 the appropriate file formats specified by @code{buffer-file-format}.
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
624 @xref{Format Conversion}. It also calls the functions in the list
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
625 @code{write-region-annotate-functions}; see @ref{Saving Properties}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
626
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
627 Normally, @code{write-region} displays the message @samp{Wrote
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
628 @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
629 nor @code{nil} nor a string, then this message is inhibited. This
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630 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
631 files that the user does not need to know about.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
632 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
633
66144
d14adceeb897 (Writing to Files): Replace `...' with `@dots{}' in `@defmac' and `@defspec'.
Juri Linkov <juri@jurta.org>
parents: 65437
diff changeset
634 @defmac with-temp-file file body@dots{}
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
635 @anchor{Definition of with-temp-file}
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
636 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
637 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
638 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
639 when finished, restoring the buffer that was current before the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
640 @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
641 in @var{body}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
642
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
643 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
644 @code{throw} or error (@pxref{Nonlocal Exits}).
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
645
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
646 See also @code{with-temp-buffer} in @ref{Definition of
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
647 with-temp-buffer,, The Current Buffer}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
648 @end defmac
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
649
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
650 @node File Locks
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
651 @section File Locks
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652 @cindex file locks
76841
fc9d442f98d2 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 75476
diff changeset
653 @cindex lock file
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
654
59877
36a927615e6d (File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents: 56981
diff changeset
655 When two users edit the same file at the same time, they are likely
36a927615e6d (File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents: 56981
diff changeset
656 to interfere with each other. Emacs tries to prevent this situation
36a927615e6d (File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents: 56981
diff changeset
657 from arising by recording a @dfn{file lock} when a file is being
36a927615e6d (File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents: 56981
diff changeset
658 modified. (File locks are not implemented on Microsoft systems.)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
659 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
660 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
661 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
662 stored in the same directory as the file you are editing.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
663
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
664 When you access files using NFS, there may be a small probability that
71957
61cb5aae3bc3 Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents: 71709
diff changeset
665 you and another user will both lock the same file ``simultaneously.''
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
666 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
667 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
668 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
669 on disk catches some cases of simultaneous editing; see
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
670 @ref{Modification Time}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 @defun file-locked-p filename
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
673 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
674 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
675 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
676 some other job.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
677
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
678 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
679 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
680 (file-locked-p "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
681 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
682 @end group
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 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
685
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
686 @defun lock-buffer &optional filename
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
687 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
688 modified. The argument @var{filename} defaults to the current buffer's
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689 visited file. Nothing is done if the current buffer is not visiting a
59877
36a927615e6d (File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents: 56981
diff changeset
690 file, or is not modified, or if the system does not support locking.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
691 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693 @defun unlock-buffer
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694 This function unlocks the file being visited in the current buffer,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
695 if the buffer is modified. If the buffer is not modified, then
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
696 the file should not be locked, so this function does nothing. It also
59877
36a927615e6d (File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents: 56981
diff changeset
697 does nothing if the current buffer is not visiting a file, or if the
36a927615e6d (File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents: 56981
diff changeset
698 system does not support locking.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
700
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
701 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
702 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
703 @code{file-locked-p} do nothing and return @code{nil}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
704
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705 @defun ask-user-about-lock file other-user
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706 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
707 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
708 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
709 this function returns determines what Emacs does next:
6555
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 @itemize @bullet
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
712 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
713 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
714 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
715
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
716 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
717 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
718 user edit the file anyway.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
720 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 @kindex file-locked
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
722 This function may instead signal a @code{file-locked} error, in which
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
723 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
724
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725 The error message for this error looks like this:
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 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 @error{} File is locked: @var{file} @var{other-user}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 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
733 name of the user who has locked the file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 @end itemize
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
736 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
737 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
738 for its usual definition is in @file{userlock.el}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739 @end defun
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 @node Information about Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742 @section Information about Files
76841
fc9d442f98d2 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 75476
diff changeset
743 @cindex file, information about
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
745 The functions described in this section all operate on strings that
62585
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
746 designate file names. With a few exceptions, all the functions have
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
747 names that begin with the word @samp{file}. These functions all
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
748 return information about actual files or directories, so their
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
749 arguments must all exist as actual files or directories unless
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
750 otherwise noted.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
751
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
752 @menu
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753 * Testing Accessibility:: Is a given file readable? Writable?
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754 * Kinds of Files:: Is it a directory? A symbolic link?
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
755 * Truenames:: Eliminating symbolic links from a file name.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756 * File Attributes:: How large is it? Any other names? Etc.
62585
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
757 * Locating Files:: How to find a file in standard places.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
758 @end menu
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
759
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
760 @node Testing Accessibility
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
761 @comment node-name, next, previous, up
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762 @subsection Testing Accessibility
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763 @cindex accessibility of a file
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 @cindex file accessibility
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
765
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
766 These functions test for permission to access a file in specific
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
767 ways. Unless explicitly stated otherwise, they recursively follow
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
768 symbolic links for their file name arguments, at all levels (at the
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
769 level of the file itself and at all levels of parent directories).
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
770
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
771 @defun file-exists-p filename
51654
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
772 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
773 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
774 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
775 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
776 containing directories, regardless of the protection of the file
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
777 itself.)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
778
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
779 If the file does not exist, or if fascist access control policies
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
780 prevent you from finding the attributes of the file, this function
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781 returns @code{nil}.
51654
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
782
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
783 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
784 given a directory name. However, symbolic links are treated
24b62b8f3def Fix minor Texinfo usage.
Richard M. Stallman <rms@gnu.org>
parents: 51558
diff changeset
785 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
786 name only if the target file exists.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
789 @defun file-readable-p filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790 This function returns @code{t} if a file named @var{filename} exists
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 and you can read it. It returns @code{nil} otherwise.
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 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
794 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
795 (file-readable-p "files.texi")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
796 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
797 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
798 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799 (file-exists-p "/usr/spool/mqueue")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803 (file-readable-p "/usr/spool/mqueue")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
805 @end group
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 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809 @c Emacs 19 feature
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
810 @defun file-executable-p filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
811 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
812 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
813 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
814 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
815 open those files if their modes permit.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
816 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818 @defun file-writable-p filename
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
819 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
820 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
821 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
822 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
823 directory.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
825 In the third example below, @file{foo} is not writable because the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826 parent directory does not exist, even though the user could create such
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827 a directory.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
829 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
830 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
831 (file-writable-p "~/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
832 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
833 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
834 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835 (file-writable-p "/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 (file-writable-p "~/no-such-dir/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
840 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
841 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
844
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
845 @c Emacs 19 feature
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
846 @defun file-accessible-directory-p dirname
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
847 This function returns @code{t} if you have permission to open existing
59877
36a927615e6d (File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents: 56981
diff changeset
848 files in the directory whose name as a file is @var{dirname};
36a927615e6d (File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents: 56981
diff changeset
849 otherwise (or if there is no such directory), it returns @code{nil}.
36a927615e6d (File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents: 56981
diff changeset
850 The value of @var{dirname} may be either a directory name (such as
36a927615e6d (File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents: 56981
diff changeset
851 @file{/foo/}) or the file name of a file which is a directory
36a927615e6d (File Locks): Not supported on MS systems.
Richard M. Stallman <rms@gnu.org>
parents: 56981
diff changeset
852 (such as @file{/foo}, without the final slash).
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854 Example: after the following,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
857 (file-accessible-directory-p "/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
858 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
859 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
860
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
861 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
862 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
863 give an error.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
864 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
865
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
866 @defun access-file filename string
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
867 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
868 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
869 using @var{string} as the error message text.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
870 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
871
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
872 @defun file-ownership-preserved-p filename
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
873 This function returns @code{t} if deleting the file @var{filename} and
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
874 then creating it anew would keep the file's owner unchanged. It also
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
875 returns @code{t} for nonexistent files.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
876
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
877 If @var{filename} is a symbolic link, then, unlike the other functions
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
878 discussed here, @code{file-ownership-preserved-p} does @emph{not}
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
879 replace @var{filename} with its target. However, it does recursively
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
880 follow symbolic links at all levels of parent directories.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
881 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
882
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
883 @defun file-newer-than-file-p filename1 filename2
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
884 @cindex file age
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
885 @cindex file modification time
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
886 This function returns @code{t} if the file @var{filename1} is
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
887 newer than file @var{filename2}. If @var{filename1} does not
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
888 exist, it returns @code{nil}. If @var{filename1} does exist, but
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
889 @var{filename2} does not, it returns @code{t}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
890
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
891 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
892 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
893 @file{no-file} doesn't exist at all.
6555
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 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
896 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
897 (file-newer-than-file-p "aug-19" "aug-20")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
898 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
899 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
900 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
901 (file-newer-than-file-p "aug-20" "aug-19")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
902 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
903 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
904 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
905 (file-newer-than-file-p "aug-19" "no-file")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
906 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
907 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
908 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
909 (file-newer-than-file-p "no-file" "aug-19")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
910 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
911 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
912 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
913
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
914 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
915 time as a list of two numbers. @xref{File Attributes}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
916 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
917
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
918 @node Kinds of Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
919 @comment node-name, next, previous, up
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
920 @subsection Distinguishing Kinds of Files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
921
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
922 This section describes how to distinguish various kinds of files, such
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
923 as directories, symbolic links, and ordinary files.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925 @defun file-symlink-p filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
926 @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
927 If the file @var{filename} is a symbolic link, the
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
928 @code{file-symlink-p} function returns the (non-recursive) link target
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
929 as a string. (Determining the file name that the link points to from
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
930 the target is nontrivial.) First, this function recursively follows
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
931 symbolic links at all levels of parent directories.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
932
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
933 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
934 @code{file-symlink-p} returns @code{nil}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
935
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
936 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
937 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
938 (file-symlink-p "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
941 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942 (file-symlink-p "sym-link")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 @result{} "foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
946 (file-symlink-p "sym-link2")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
947 @result{} "sym-link"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
948 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
949 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
950 (file-symlink-p "/bin")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
951 @result{} "/pub/bin"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
952 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
953 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
954
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
955 @c !!! file-symlink-p: should show output of ls -l for comparison
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
956 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
957
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
958 The next two functions recursively follow symbolic links at
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
959 all levels for @var{filename}.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
960
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
961 @defun file-directory-p filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
962 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
963 existing directory, @code{nil} otherwise.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
964
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
965 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
966 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967 (file-directory-p "~rms")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
968 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
970 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
971 (file-directory-p "~rms/lewis/files.texi")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
975 (file-directory-p "~rms/lewis/no-such-file")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
978 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
979 (file-directory-p "$HOME")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
981 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
982 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983 (file-directory-p
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984 (substitute-in-file-name "$HOME"))
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
989
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
990 @defun file-regular-p filename
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
991 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
992 a regular file (not a directory, named pipe, terminal, or
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
993 other I/O device).
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
994 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
995
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
996 @node Truenames
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
997 @subsection Truenames
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
998 @cindex truename (of file)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
999
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1000 @c Emacs 19 features
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1001 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
1002 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
1003 @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
1004 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
1005 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
1006 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
1007 because they eliminate symbolic links as a cause of name variation.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1008
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1009 @defun file-truename filename
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1010 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
1011 @var{filename}. The argument must be an absolute file name.
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1012
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1013 This function does not expand environment variables. Only
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1014 @code{substitute-in-file-name} does that. @xref{Definition of
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1015 substitute-in-file-name}.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1016
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1017 If you may need to follow symbolic links preceding @samp{..}@:
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1018 appearing as a name component, you should make sure to call
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1019 @code{file-truename} without prior direct or indirect calls to
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1020 @code{expand-file-name}, as otherwise the file name component
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1021 immediately preceding @samp{..} will be ``simplified away'' before
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1022 @code{file-truename} is called. To eliminate the need for a call to
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1023 @code{expand-file-name}, @code{file-truename} handles @samp{~} in the
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1024 same way that @code{expand-file-name} does. @xref{File Name
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1025 Expansion,, Functions that Expand Filenames}.
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1026 @end defun
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1027
52003
0509fad02151 (Truenames): Add LIMIT arg to file-chase-links.
Richard M. Stallman <rms@gnu.org>
parents: 51913
diff changeset
1028 @defun file-chase-links filename &optional limit
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1029 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
1030 until it finds a file name which is not the name of a symbolic link.
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1031 Then it returns that file name. This function does @emph{not} follow
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1032 symbolic links at the level of parent directories.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1033
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1034 If you specify a number for @var{limit}, then after chasing through
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1035 that many links, the function just returns what it has even if that is
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1036 still a symbolic link.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1037 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1038
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1039 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
1040 @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
1041 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
1042 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
1043 we would have:
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1044
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1045 @example
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1046 (file-chase-links "/usr/foo/hello")
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1047 ;; @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
1048 @result{} "/usr/foo/hello"
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1049 (file-truename "/usr/foo/hello")
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1050 ;; @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
1051 @result{} "/home/foo/hello"
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1052 @end example
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1053
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1054 @xref{Buffer File Name}, for related information.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1055
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1056 @node File Attributes
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057 @comment node-name, next, previous, up
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 @subsection Other Information about Files
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 This section describes the functions for getting detailed information
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 about a file, other than its contents. This information includes the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062 mode bits that control access permission, the owner and group numbers,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063 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
1064 and modification.
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 @defun file-modes filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067 @cindex permission
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068 @cindex file attributes
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1069 This function returns the mode bits of @var{filename}, as an integer.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1070 The mode bits are also called the file permissions, and they specify
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1071 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
1072 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
1073 is 1, then the file is writable by all users, etc.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1074
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1075 The highest value returnable is 4095 (7777 octal), meaning that
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1076 everyone has read, write, and execute permission, that the @acronym{SUID} bit
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1077 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
1078
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1079 If @var{filename} does not exist, @code{file-modes} returns @code{nil}.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1080
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1081 This function recursively follows symbolic links at all levels.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1082
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1083 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1084 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1085 (file-modes "~/junk/diffs")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1086 @result{} 492 ; @r{Decimal integer.}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1087 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1088 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1089 (format "%o" 492)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1090 @result{} "754" ; @r{Convert to octal.}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1091 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1092
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1093 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1094 (set-file-modes "~/junk/diffs" 438)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1095 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1096 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1097
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1098 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1099 (format "%o" 438)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1100 @result{} "666" ; @r{Convert to octal.}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1101 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1102
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1103 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1104 % ls -l diffs
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1105 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1106 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1107 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1108 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1109
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1110 If the @var{filename} argument to the next two functions is a symbolic
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1111 link, then these function do @emph{not} replace it with its target.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1112 However, they both recursively follow symbolic links at all levels of
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1113 parent directories.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1114
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1115 @defun file-nlinks filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1116 This functions returns the number of names (i.e., hard links) that
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1117 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
1118 returns @code{nil}. Note that symbolic links have no effect on this
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1119 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
1120 link to.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1121
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1122 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1123 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1124 % ls -l foo*
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1125 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1126 -rw-rw-rw- 2 rms 4 Aug 19 01:27 foo1
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1127 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1128
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1129 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1130 (file-nlinks "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1131 @result{} 2
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1132 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1133 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1134 (file-nlinks "doesnt-exist")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1135 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1136 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1137 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1138 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1139
56215
c9aa4127a482 Reposition @anchor's.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56207
diff changeset
1140 @defun file-attributes filename &optional id-format
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1141 @anchor{Definition of file-attributes}
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1142 This function returns a list of attributes of file @var{filename}. If
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1143 the specified file cannot be opened, it returns @code{nil}.
53109
420dc7ac8867 (File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents: 52978
diff changeset
1144 The optional parameter @var{id-format} specifies the preferred format
420dc7ac8867 (File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents: 52978
diff changeset
1145 of attributes @acronym{UID} and @acronym{GID} (see below)---the
420dc7ac8867 (File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents: 52978
diff changeset
1146 valid values are @code{'string} and @code{'integer}. The latter is
420dc7ac8867 (File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents: 52978
diff changeset
1147 the default, but we plan to change that, so you should specify a
420dc7ac8867 (File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents: 52978
diff changeset
1148 non-@code{nil} value for @var{id-format} if you use the returned
420dc7ac8867 (File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents: 52978
diff changeset
1149 @acronym{UID} or @acronym{GID}.
6555
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 The elements of the list, in order, are:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1152
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1153 @enumerate 0
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1154 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1155 @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
1156 linked to), or @code{nil} for a text file.
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 @c Wordy so as to prevent an overfull hbox. --rjc 15mar92
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1159 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1160 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
1161 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
1162 (@pxref{Changing Files}).
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164 @item
75476
330094c564c4 (File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
1165 The file's @acronym{UID}, normally as a string. However, if it does
330094c564c4 (File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
1166 not correspond to a named user, the value is an integer or a floating
330094c564c4 (File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
1167 point number.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1168
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1169 @item
75476
330094c564c4 (File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
1170 The file's @acronym{GID}, likewise.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1171
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1172 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1173 The time of last access, as a list of two integers.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1174 The first integer has the high-order 16 bits of time,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175 the second has the low 16 bits. (This is similar to the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176 value of @code{current-time}; see @ref{Time of Day}.)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1177
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1178 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1179 The time of last modification as a list of two integers (as above).
77006
1f4b88ab053d Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
1180 @cindex modification time of file
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1182 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1183 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
1184
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1185 @item
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
1186 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
1187 Lisp integer, this is a floating point number.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1188
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1189 @item
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
1190 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
1191 as in @samp{ls -l}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1192
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1193 @item
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1194 @code{t} if the file's @acronym{GID} would change if file were
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1195 deleted and recreated; @code{nil} otherwise.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1196
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1197 @item
17919
eb712b69e495 The inode number can be an integer.
Richard M. Stallman <rms@gnu.org>
parents: 17398
diff changeset
1198 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
1199 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
1200 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
1201 holds the low 16 bits.
6555
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 @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
1204 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
1205 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
1206 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
1207 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
1208 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
1209 values for both of these numbers.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1210 @end enumerate
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1211
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1212 For example, here are the file attributes for @file{files.texi}:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1213
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1214 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1215 @group
53109
420dc7ac8867 (File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents: 52978
diff changeset
1216 (file-attributes "files.texi" 'string)
420dc7ac8867 (File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents: 52978
diff changeset
1217 @result{} (nil 1 "lh" "users"
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
1218 (8489 20284)
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
1219 (8489 20284)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1220 (8489 20285)
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
1221 14906 "-rw-rw-rw-"
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1222 nil 129500 -32252)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1223 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1224 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1225
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1226 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1227 and here is how the result is interpreted:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1228
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1229 @table @code
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1230 @item nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1231 is neither a directory nor a symbolic link.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1232
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1233 @item 1
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1234 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
1235 directory).
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1236
53109
420dc7ac8867 (File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents: 52978
diff changeset
1237 @item "lh"
420dc7ac8867 (File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents: 52978
diff changeset
1238 is owned by the user with name "lh".
420dc7ac8867 (File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents: 52978
diff changeset
1239
420dc7ac8867 (File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents: 52978
diff changeset
1240 @item "users"
420dc7ac8867 (File Attributes): Describe new parameter ID-FORMAT.
Lars Hansen <larsh@soem.dk>
parents: 52978
diff changeset
1241 is in the group with name "users".
6555
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 @item (8489 20284)
12522
75d5cd591947 Fix minor error.
Richard M. Stallman <rms@gnu.org>
parents: 12226
diff changeset
1244 was last accessed on Aug 19 00:09.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1245
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1246 @item (8489 20284)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1247 was last modified on Aug 19 00:09.
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 @item (8489 20285)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1250 last had its inode changed on Aug 19 00:09.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1251
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1252 @item 14906
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1253 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
1254 if some of the bytes belong to multibyte sequences.)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1255
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1256 @item "-rw-rw-rw-"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1257 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
1258
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1259 @item nil
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
1260 would retain the same @acronym{GID} if it were recreated.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1261
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1262 @item 129500
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1263 has an inode number of 129500.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1264 @item -32252
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1265 is on file system number -32252.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1266 @end table
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1267 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1268
62585
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1269 @node Locating Files
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1270 @subsection How to Locate Files in Standard Places
77006
1f4b88ab053d Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
1271 @cindex locate file in path
1f4b88ab053d Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
1272 @cindex find file in path
62585
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1273
62856
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1274 This section explains how to search for a file in a list of
77006
1f4b88ab053d Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
1275 directories (a @dfn{path}). One example is when you need to look for
1f4b88ab053d Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
1276 a program's executable file, e.g., to find out whether a given program
1f4b88ab053d Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
1277 is installed on the user's system. Another example is the search for
62585
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1278 Lisp libraries (@pxref{Library Search}). Such searches generally need
62856
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1279 to try various possible file name extensions, in addition to various
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1280 possible directories. Emacs provides a function for such a
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1281 generalized search for a file.
62585
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1282
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1283 @defun locate-file filename path &optional suffixes predicate
62856
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1284 This function searches for a file whose name is @var{filename} in a
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1285 list of directories given by @var{path}, trying the suffixes in
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1286 @var{suffixes}. If it finds such a file, it returns the full
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1287 @dfn{absolute file name} of the file (@pxref{Relative File Names});
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1288 otherwise it returns @code{nil}.
62585
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1289
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1290 The optional argument @var{suffixes} gives the list of file-name
62856
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1291 suffixes to append to @var{filename} when searching.
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1292 @code{locate-file} tries each possible directory with each of these
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1293 suffixes. If @var{suffixes} is @code{nil}, or @code{("")}, then there
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1294 are no suffixes, and @var{filename} is used only as-is. Typical
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1295 values of @var{suffixes} are @code{exec-suffixes} (@pxref{Subprocess
69201
0b687e350e7e (Locating Files): Suggest additional values for the
Luc Teirlinck <teirllm@auburn.edu>
parents: 69015
diff changeset
1296 Creation, exec-suffixes}), @code{load-suffixes},
0b687e350e7e (Locating Files): Suggest additional values for the
Luc Teirlinck <teirllm@auburn.edu>
parents: 69015
diff changeset
1297 @code{load-file-rep-suffixes} and the return value of the function
0b687e350e7e (Locating Files): Suggest additional values for the
Luc Teirlinck <teirllm@auburn.edu>
parents: 69015
diff changeset
1298 @code{get-load-suffixes} (@pxref{Load Suffixes}).
62856
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1299
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1300 Typical values for @var{path} are @code{exec-path} (@pxref{Subprocess
62585
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1301 Creation, exec-path}) when looking for executable programs or
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1302 @code{load-path} (@pxref{Library Search, load-path}) when looking for
62856
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1303 Lisp files. If @var{filename} is absolute, @var{path} has no effect,
19deaa395e85 (Locating Files): Clean up the text.
Richard M. Stallman <rms@gnu.org>
parents: 62585
diff changeset
1304 but the suffixes in @var{suffixes} are still tried.
62585
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1305
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1306 The optional argument @var{predicate}, if non-@code{nil}, specifies
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1307 the predicate function to use for testing whether a candidate file is
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1308 suitable. The predicate function is passed the candidate file name as
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1309 its single argument. If @var{predicate} is @code{nil} or unspecified,
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1310 @code{locate-file} uses @code{file-readable-p} as the default
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1311 predicate. Useful non-default predicates include
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1312 @code{file-executable-p}, @code{file-directory-p}, and other
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1313 predicates described in @ref{Kinds of Files}.
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1314
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1315 For compatibility, @var{predicate} can also be one of the symbols
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1316 @code{executable}, @code{readable}, @code{writable}, @code{exists}, or
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1317 a list of one or more of these symbols.
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1318 @end defun
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1319
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1320 @defun executable-find program
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1321 This function searches for the executable file of the named
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1322 @var{program} and returns the full absolute name of the executable,
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1323 including its file-name extensions, if any. It returns @code{nil} if
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1324 the file is not found. The functions searches in all the directories
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1325 in @code{exec-path} and tries all the file-name extensions in
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1326 @code{exec-suffixes}.
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1327 @end defun
78962e585d20 (Locating Files): New subsection. Describe locate-file and executable-find.
Eli Zaretskii <eliz@gnu.org>
parents: 61949
diff changeset
1328
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1329 @node Changing Files
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1330 @section Changing File Names and Attributes
77006
1f4b88ab053d Improve index entries. Remove redundant/useless ones.
Richard M. Stallman <rms@gnu.org>
parents: 76841
diff changeset
1331 @c @cindex renaming files Duplicates rename-file
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1332 @cindex copying files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1333 @cindex deleting files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1334 @cindex linking files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1335 @cindex setting modes of files
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1336
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1337 The functions in this section rename, copy, delete, link, and set the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1338 modes of files.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1339
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1340 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
1341 name of @var{newname} already exists, the actions taken depend on the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1342 value of the argument @var{ok-if-already-exists}:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1343
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1344 @itemize @bullet
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1345 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1346 Signal a @code{file-already-exists} error if
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1347 @var{ok-if-already-exists} is @code{nil}.
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 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1350 Request confirmation if @var{ok-if-already-exists} is a number.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1351
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1352 @item
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1353 Replace the old file without confirmation if @var{ok-if-already-exists}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1354 is any other value.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1355 @end itemize
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1356
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1357 The next four commands all recursively follow symbolic links at all
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1358 levels of parent directories for their first argument, but, if that
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1359 argument is itself a symbolic link, then only @code{copy-file}
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1360 replaces it with its (recursive) target.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1361
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1362 @deffn Command add-name-to-file oldname newname &optional ok-if-already-exists
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1363 @cindex file with multiple names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1364 @cindex file hard link
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1365 This function gives the file named @var{oldname} the additional name
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1366 @var{newname}. This means that @var{newname} becomes a new ``hard
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1367 link'' to @var{oldname}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1368
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1369 In the first part of the following example, we list two files,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1370 @file{foo} and @file{foo3}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1371
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1372 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1373 @group
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1374 % ls -li fo*
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1375 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
1376 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
1377 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1378 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1379
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
1380 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
1381 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
1382 @file{foo2}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1383
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1384 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1385 @group
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1386 (add-name-to-file "foo" "foo2")
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1387 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1388 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1389
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1390 @group
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1391 % ls -li fo*
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1392 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
1393 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
1394 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
1395 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1396 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1397
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1398 Finally, we evaluate the following:
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1399
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1400 @example
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1401 (add-name-to-file "foo" "foo3" t)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1402 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1403
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1404 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1405 and list the files again. Now there are three names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1406 for one file: @file{foo}, @file{foo2}, and @file{foo3}. The old
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1407 contents of @file{foo3} are lost.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1408
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1409 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1410 @group
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1411 (add-name-to-file "foo1" "foo3")
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1412 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1413 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1414
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1415 @group
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1416 % ls -li fo*
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1417 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
1418 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
1419 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
1420 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1421 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1422
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1423 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
1424 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
1425 by copying the file instead.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1426
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1427 See also @code{file-nlinks} in @ref{File Attributes}.
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1428 @end deffn
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1429
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1430 @deffn Command rename-file filename newname &optional ok-if-already-exists
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1431 This command renames the file @var{filename} as @var{newname}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1432
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1433 If @var{filename} has additional names aside from @var{filename}, it
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1434 continues to have those names. In fact, adding the name @var{newname}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1435 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
1436 same effect as renaming, aside from momentary intermediate states.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1437 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1438
71003
7733ed75db62 * files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents: 70657
diff changeset
1439 @deffn Command copy-file oldname newname &optional ok-if-exists time preserve-uid-gid
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1440 This command copies the file @var{oldname} to @var{newname}. An
51913
3abc365e9d90 (Changing Files): copy-file allows dir as NEWNAME.
Richard M. Stallman <rms@gnu.org>
parents: 51793
diff changeset
1441 error is signaled if @var{oldname} does not exist. If @var{newname}
3abc365e9d90 (Changing Files): copy-file allows dir as NEWNAME.
Richard M. Stallman <rms@gnu.org>
parents: 51793
diff changeset
1442 names a directory, it copies @var{oldname} into that directory,
3abc365e9d90 (Changing Files): copy-file allows dir as NEWNAME.
Richard M. Stallman <rms@gnu.org>
parents: 51793
diff changeset
1443 preserving its final name component.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1444
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1445 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
1446 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
1447 some operating systems.) If setting the time gets an error,
71003
7733ed75db62 * files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents: 70657
diff changeset
1448 @code{copy-file} signals a @code{file-date-error} error. In an
7733ed75db62 * files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents: 70657
diff changeset
1449 interactive call, a prefix argument specifies a non-@code{nil} value
7733ed75db62 * files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents: 70657
diff changeset
1450 for @var{time}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1451
51558
5a85c7c1d3ab (Changing Files): copy-file copies file modes, too.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 51020
diff changeset
1452 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
1453
71003
7733ed75db62 * files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents: 70657
diff changeset
1454 If argument @var{preserve-uid-gid} is @code{nil}, we let the operating
7733ed75db62 * files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents: 70657
diff changeset
1455 system decide the user and group ownership of the new file (this is
7733ed75db62 * files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents: 70657
diff changeset
1456 usually set to the user running Emacs). If @var{preserve-uid-gid} is
7733ed75db62 * files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents: 70657
diff changeset
1457 non-@code{nil}, we attempt to copy the user and group ownership of the
7733ed75db62 * files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents: 70657
diff changeset
1458 file. This works only on some operating systems, and only if you have
7733ed75db62 * files.texi (Changing Files): Document updated argument list for
Chong Yidong <cyd@stupidchicken.com>
parents: 70657
diff changeset
1459 the correct permissions to do so.
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1460 @end deffn
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1461
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1462 @deffn Command make-symbolic-link filename newname &optional ok-if-exists
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1463 @pindex ln
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1464 @kindex file-already-exists
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1465 This command makes a symbolic link to @var{filename}, named
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1466 @var{newname}. This is like the shell command @samp{ln -s
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1467 @var{filename} @var{newname}}.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1468
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1469 This function is not available on systems that don't support symbolic
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1470 links.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1471 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1472
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1473 @deffn Command delete-file filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1474 @pindex rm
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1475 This command deletes the file @var{filename}, like the shell command
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1476 @samp{rm @var{filename}}. If the file has multiple names, it continues
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1477 to exist under the other names.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1478
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1479 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
1480 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
1481 deletable if its directory is writable.)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1482
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1483 If @var{filename} is a symbolic link, @code{delete-file} does not
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1484 replace it with its target, but it does follow symbolic links at all
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1485 levels of parent directories.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1486
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1487 See also @code{delete-directory} in @ref{Create/Delete Dirs}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1488 @end deffn
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1489
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1490 @defun define-logical-name varname string
54025
8659505a7f3d (Changing Files): Fix argname.
Richard M. Stallman <rms@gnu.org>
parents: 53575
diff changeset
1491 This function defines the logical name @var{varname} to have the value
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1492 @var{string}. It is available only on VMS.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1493 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1494
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1495 @defun set-file-modes filename mode
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1496 This function sets mode bits of @var{filename} to @var{mode} (which
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1497 must be an integer). Only the low 12 bits of @var{mode} are used.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1498 This function recursively follows symbolic links at all levels for
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1499 @var{filename}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1500 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1501
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1502 @c Emacs 19 feature
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1503 @defun set-default-file-modes mode
47514
e0d6f0b369d1 Add `umask' to the concept index.
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 46956
diff changeset
1504 @cindex umask
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1505 This function sets the default file protection for new files created by
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1506 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
1507 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
1508 file execute permission even if the default file protection allows
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1509 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
1510 the bitwise complement of the ``umask'' value.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1511
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1512 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
1513 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
1514 for octal character codes to enter @var{mode}; for example,
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1515
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1516 @example
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1517 (set-default-file-modes ?\644)
25557ce6a3a0 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27259
diff changeset
1518 @end example
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1519
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1520 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
1521 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
1522 the default file protection has no effect.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1523 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1524
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1525 @defun default-file-modes
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1526 This function returns the current default protection value.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1527 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1528
55192
dd5538a91d27 (Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents: 54861
diff changeset
1529 @defun set-file-times filename &optional time
dd5538a91d27 (Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents: 54861
diff changeset
1530 This function sets the access and modification times of @var{filename}
dd5538a91d27 (Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents: 54861
diff changeset
1531 to @var{time}. The return value is @code{t} if the times are successfully
dd5538a91d27 (Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents: 54861
diff changeset
1532 set, otherwise it is @code{nil}. @var{time} defaults to the current
dd5538a91d27 (Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents: 54861
diff changeset
1533 time and must be in the format returned by @code{current-time}
dd5538a91d27 (Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents: 54861
diff changeset
1534 (@pxref{Time of Day}).
dd5538a91d27 (Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents: 54861
diff changeset
1535 @end defun
dd5538a91d27 (Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents: 54861
diff changeset
1536
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
1537 @cindex MS-DOS and file modes
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
1538 @cindex file modes and MS-DOS
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
1539 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
1540 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
1541 standard executable extensions, such as @file{.com}, @file{.bat},
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1542 @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
1543 @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
1544 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
1545 @code{file-modes} and @code{file-attributes}. Directories are also
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1546 reported with executable bit set, for compatibility with Unix.
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
1547
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1548 @node File Names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1549 @section File Names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1550 @cindex file names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1551
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1552 Files are generally referred to by their names, in Emacs as elsewhere.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1553 File names in Emacs are represented as strings. The functions that
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1554 operate on a file all expect a file name argument.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1556 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
1557 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
1558 part of a name to construct related file names. This section describes
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1559 how to manipulate file names.
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 The functions in this section do not actually access files, so they
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1562 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
1563 directory.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1564
28635
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1565 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
1566 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
1567 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
1568 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
1569 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
1570 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
1571 and work properly on all systems without change.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1572
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1573 @menu
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1574 * 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
1575 * 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
1576 * Directory Names:: A directory's name as a directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1577 is different from its name as a file.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1578 * File Name Expansion:: Converting relative file names to absolute ones.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1579 * Unique File Names:: Generating names for temporary files.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1580 * 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
1581 * 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
1582 how to handle various operating systems simply.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1583 @end menu
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1584
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1585 @node File Name Components
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1586 @subsection File Name Components
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1587 @cindex directory part (of file name)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1588 @cindex nondirectory part (of file name)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1589 @cindex version number (in file name)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1590
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1591 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
1592 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
1593 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
1594 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
1595 (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
1596 Concatenating these two parts reproduces the original file name.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1597
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
1598 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
1599 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
1600 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
1601 are complicated.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1602
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1603 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
1604 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
1605 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
1606 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
1607 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
1608 found mostly in directory lists.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1609
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1610 @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
1611 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
1612 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
1613 @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
1614
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1615 On GNU and Unix systems, a string returned by this function always
70538
08c09d92fecc Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 69201
diff changeset
1616 ends in a slash. On MS-DOS it can also end in a colon. On VMS, it
46956
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1617 returns a string ending in one of the three characters @samp{:},
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1618 @samp{]}, or @samp{>}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1619
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1620 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1621 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1622 (file-name-directory "lewis/foo") ; @r{Unix example}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1623 @result{} "lewis/"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1624 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1625 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1626 (file-name-directory "foo") ; @r{Unix example}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1627 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1628 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1629 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1630 (file-name-directory "[X]FOO.TMP") ; @r{VMS example}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1631 @result{} "[X]"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1632 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1633 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1634 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1635
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1636 @defun file-name-nondirectory filename
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
1637 This function returns the nondirectory part of @var{filename}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1638
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1639 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1640 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1641 (file-name-nondirectory "lewis/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1642 @result{} "foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1643 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1644 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1645 (file-name-nondirectory "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1646 @result{} "foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1647 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1648 @group
46956
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1649 (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
1650 @result{} ""
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1651 @end group
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1652 @group
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1653 ;; @r{The following example is accurate only on VMS.}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1654 (file-name-nondirectory "[X]FOO.TMP")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1655 @result{} "FOO.TMP"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1656 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1657 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1658 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1659
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1660 @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
1661 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
1662 backup version numbers, or trailing tildes discarded.
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1663
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
1664 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
1665 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
1666 return value, but backup version numbers are kept.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1667
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1668 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1669 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1670 (file-name-sans-versions "~rms/foo.~1~")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1671 @result{} "~rms/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1672 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1673 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1674 (file-name-sans-versions "~rms/foo~")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1675 @result{} "~rms/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1676 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1677 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1678 (file-name-sans-versions "~rms/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1679 @result{} "~rms/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1680 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1681 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1682 ;; @r{The following example applies to VMS only.}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1683 (file-name-sans-versions "foo;23")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1684 @result{} "foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1685 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1686 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1687 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1688
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1689 @defun file-name-extension filename &optional period
71957
61cb5aae3bc3 Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents: 71709
diff changeset
1690 This function returns @var{filename}'s final ``extension,'' if any,
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1691 after applying @code{file-name-sans-versions} to remove any
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1692 version/backup part. The extension, in a file name, is the part that
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1693 starts with the last @samp{.} in the last name component (minus
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1694 any version/backup part).
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1695
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1696 This function returns @code{nil} for extensionless file names such as
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1697 @file{foo}. It returns @code{""} for null extensions, as in
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1698 @file{foo.}. If the last component of a file name begins with a
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1699 @samp{.}, that @samp{.} doesn't count as the beginning of an
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1700 extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1701 @samp{.emacs}.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1702
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1703 If @var{period} is non-@code{nil}, then the returned value includes
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1704 the period that delimits the extension, and if @var{filename} has no
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1705 extension, the value is @code{""}.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1706 @end defun
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1707
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
1708 @defun file-name-sans-extension filename
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1709 This function returns @var{filename} minus its extension, if any. The
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1710 version/backup part, if present, is only removed if the file has an
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1711 extension. For example,
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1712
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1713 @example
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1714 (file-name-sans-extension "foo.lose.c")
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1715 @result{} "foo.lose"
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1716 (file-name-sans-extension "big.hack/foo")
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1717 @result{} "big.hack/foo"
40188
cd1cd95ca64e (File Name Components): Update the description of
Eli Zaretskii <eliz@gnu.org>
parents: 39883
diff changeset
1718 (file-name-sans-extension "/my/home/.emacs")
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
1719 @result{} "/my/home/.emacs"
40188
cd1cd95ca64e (File Name Components): Update the description of
Eli Zaretskii <eliz@gnu.org>
parents: 39883
diff changeset
1720 (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
1721 @result{} "/my/home/.emacs"
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1722 (file-name-sans-extension "~/foo.el.~3~")
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1723 @result{} "~/foo"
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1724 (file-name-sans-extension "~/foo.~3~")
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1725 @result{} "~/foo.~3~"
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1726 @end example
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1727
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1728 Note that the @samp{.~3~} in the two last examples is the backup part,
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1729 not an extension.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
1730 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
1731
28635
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1732 @ignore
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
1733 Andrew Innes says that this
28635
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1734
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1735 @c @defvar directory-sep-char
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1736 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
1737 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
1738 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
1739 use backslashes in their output.
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1740
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1741 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
1742 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
1743 value of @code{?/}.
28608
c46c2efa3731 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28074
diff changeset
1744 @end defvar
28635
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
1745 @end ignore
28608
c46c2efa3731 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28074
diff changeset
1746
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1747 @node Relative File Names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1748 @subsection Absolute and Relative File Names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1749 @cindex absolute file name
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1750 @cindex relative file name
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1751
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1752 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
1753 root directory. A file name can specify all the directory names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1754 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
1755 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
1756 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
1757 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
1758 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
1759 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
1760 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
1761 @dfn{drive letter}. The rules on VMS are complicated.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1762
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1763 @defun file-name-absolute-p filename
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1764 This function returns @code{t} if file @var{filename} is an absolute
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1765 file name, @code{nil} otherwise. On VMS, this function understands both
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1766 Unix syntax and VMS syntax.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1767
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1768 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1769 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1770 (file-name-absolute-p "~rms/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1771 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1772 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1773 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1774 (file-name-absolute-p "rms/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1775 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1776 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1777 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1778 (file-name-absolute-p "/user/rms/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1779 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1780 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1781 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1782 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1783
69015
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1784 Given a possibly relative file name, you can convert it to an
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1785 absolute name using @code{expand-file-name} (@pxref{File Name
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1786 Expansion}). This function converts absolute file names to relative
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1787 names:
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1788
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1789 @defun file-relative-name filename &optional directory
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1790 This function tries to return a relative name that is equivalent to
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1791 @var{filename}, assuming the result will be interpreted relative to
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1792 @var{directory} (an absolute directory name or directory file name).
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1793 If @var{directory} is omitted or @code{nil}, it defaults to the
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1794 current buffer's default directory.
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1795
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1796 On some operating systems, an absolute file name begins with a device
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1797 name. On such systems, @var{filename} has no relative equivalent based
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1798 on @var{directory} if they start with two different device names. In
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1799 this case, @code{file-relative-name} returns @var{filename} in absolute
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1800 form.
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1801
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1802 @example
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1803 (file-relative-name "/foo/bar" "/foo/")
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1804 @result{} "bar"
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1805 (file-relative-name "/foo/bar" "/hack/")
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1806 @result{} "../foo/bar"
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1807 @end example
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1808 @end defun
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1809
46956
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1810 @node Directory Names
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1811 @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
1812 @subsection Directory Names
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1813 @cindex directory name
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1814 @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
1815
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1816 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
1817 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
1818 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
1819 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
1820 the same entity are related by a syntactic transformation. On GNU and
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1821 Unix systems, this is simple: a directory name ends in a slash,
70538
08c09d92fecc Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 69201
diff changeset
1822 whereas the directory's name as a file lacks that slash. On MS-DOS and
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1823 VMS, the relationship is more complicated.
46956
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1824
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1825 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
1826 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
1827 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
1828 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
1829 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
1830
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1831 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
1832 names. They do nothing special with environment variable substitutions
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1833 such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}.
46956
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1834
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1835 @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
1836 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
1837 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
1838 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
1839 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
1840 @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
1841
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1842 @example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1843 @group
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1844 (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
1845 @result{} "~rms/lewis/"
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1846 @end group
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1847 @end example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1848 @end defun
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1849
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1850 @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
1851 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
1852 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
1853 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
1854 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
1855 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
1856
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1857 @example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1858 @group
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1859 (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
1860 @result{} "~lewis"
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1861 @end group
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1862 @end example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1863 @end defun
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1864
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1865 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
1866 using @code{concat}:
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1867
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1868 @example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1869 (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
1870 @end example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1871
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1872 @noindent
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1873 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
1874 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
1875 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
1876
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1877 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
1878 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
1879 @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
1880
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1881 @example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1882 (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
1883 @end example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1884
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1885 @noindent
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1886 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
1887
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1888 @example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1889 ;;; @r{Wrong!}
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1890 (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
1891 @end example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1892
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1893 @noindent
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1894 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
1895 @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
1896
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1897 @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
1898 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
1899 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
1900 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
1901 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
1902 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
1903 abbreviation instead.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1904
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1905 @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
1906 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
1907 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
1908 @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
1909 @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
1910 actually a regular expression; it should always start with @samp{^}.
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1911 The @var{to} string should be an ordinary absolute directory name. Do
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1912 not use @samp{~} to stand for a home directory in that string. The
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1913 function @code{abbreviate-file-name} performs these substitutions.
46956
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1914
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1915 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
1916 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
1917
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1918 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
1919 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
1920 and so on.
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1921
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1922 @example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1923 (("^/home/fsf" . "/fsf")
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1924 ("^/home/gp" . "/gp")
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1925 ("^/home/gd" . "/gd"))
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1926 @end example
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1927 @end defvar
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1928
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1929 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
1930 function:
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1931
56215
c9aa4127a482 Reposition @anchor's.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56207
diff changeset
1932 @defun abbreviate-file-name filename
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1933 @anchor{Definition of abbreviate-file-name}
46956
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1934 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
1935 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
1936 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
1937 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
1938 @end defun
2c01ee3e5305 Move the node Relative Files before Directory Names. Show what
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
1939
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1940 @node File Name Expansion
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1941 @subsection Functions that Expand Filenames
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1942 @cindex expansion of file names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1943
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1944 @dfn{Expansion} of a file name means converting a relative file name
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1945 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
1946 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
1947 be expanded. Expansion also simplifies file names by eliminating
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1948 redundancies such as @file{./} and @file{@var{name}/../}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1949
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1950 @defun expand-file-name filename &optional directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1951 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
1952 @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
1953 if @var{filename} is relative. (The value of @var{directory} should
69015
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1954 itself be an absolute directory name or directory file name; it may
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1955 start with @samp{~}.) Otherwise, the current buffer's value of
761f4a4fe6e8 (Relative File Names): Move file-relative-name here.
Richard M. Stallman <rms@gnu.org>
parents: 68648
diff changeset
1956 @code{default-directory} is used. For example:
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1957
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1958 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1959 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1960 (expand-file-name "foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1961 @result{} "/xcssun/users/rms/lewis/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1962 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1963 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1964 (expand-file-name "../foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1965 @result{} "/xcssun/users/rms/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1966 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1967 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1968 (expand-file-name "foo" "/usr/spool/")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1969 @result{} "/usr/spool/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1970 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1971 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1972 (expand-file-name "$HOME/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1973 @result{} "/xcssun/users/rms/lewis/$HOME/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1974 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1975 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1976
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1977 If the part of the combined file name before the first slash is
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1978 @samp{~}, it expands to the value of the @env{HOME} environment
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1979 variable (usually your home directory). If the part before the first
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1980 slash is @samp{~@var{user}} and if @var{user} is a valid login name,
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1981 it expands to @var{user}'s home directory.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
1982
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1983 Filenames containing @samp{.} or @samp{..} are simplified to their
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1984 canonical form:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1985
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1986 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1987 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1988 (expand-file-name "bar/../foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1989 @result{} "/xcssun/users/rms/lewis/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1990 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1991 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1992
77361
916f8aa2138d (File Name Expansion): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77302
diff changeset
1993 In some cases, a leading @samp{..} component can remain in the output:
77302
95a196e2e465 (File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents: 77006
diff changeset
1994
95a196e2e465 (File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents: 77006
diff changeset
1995 @example
95a196e2e465 (File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents: 77006
diff changeset
1996 @group
95a196e2e465 (File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents: 77006
diff changeset
1997 (expand-file-name "../home" "/")
95a196e2e465 (File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents: 77006
diff changeset
1998 @result{} "/../home"
95a196e2e465 (File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents: 77006
diff changeset
1999 @end group
95a196e2e465 (File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents: 77006
diff changeset
2000 @end example
95a196e2e465 (File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents: 77006
diff changeset
2001
77361
916f8aa2138d (File Name Expansion): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77302
diff changeset
2002 @noindent
916f8aa2138d (File Name Expansion): Clarify previous change.
Richard M. Stallman <rms@gnu.org>
parents: 77302
diff changeset
2003 This is for the sake of filesystems that have the concept of a
77302
95a196e2e465 (File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents: 77006
diff changeset
2004 ``superroot'' above the root directory @file{/}. On other filesystems,
95a196e2e465 (File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents: 77006
diff changeset
2005 @file{/../} is interpreted exactly the same as @file{/}.
95a196e2e465 (File Name Expansion): Mention "superroot".
Glenn Morris <rgm@gnu.org>
parents: 77006
diff changeset
2006
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2007 Note that @code{expand-file-name} does @emph{not} expand environment
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2008 variables; only @code{substitute-in-file-name} does that.
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2009
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2010 Note also that @code{expand-file-name} does not follow symbolic links
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2011 at any level. This results in a difference between the way
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2012 @code{file-truename} and @code{expand-file-name} treat @samp{..}.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2013 Assuming that @samp{/tmp/bar} is a symbolic link to the directory
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2014 @samp{/tmp/foo/bar} we get:
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2015
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2016 @example
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2017 @group
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2018 (file-truename "/tmp/bar/../myfile")
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2019 @result{} "/tmp/foo/myfile"
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2020 @end group
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2021 @group
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2022 (expand-file-name "/tmp/bar/../myfile")
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2023 @result{} "/tmp/myfile"
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2024 @end group
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2025 @end example
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2026
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2027 If you may need to follow symbolic links preceding @samp{..}, you
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2028 should make sure to call @code{file-truename} without prior direct or
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2029 indirect calls to @code{expand-file-name}. @xref{Truenames}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2030 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2031
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2032 @defvar default-directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2033 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
2034 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
2035 with @samp{~}. This variable is buffer-local in every buffer.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2036
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2037 @code{expand-file-name} uses the default directory when its second
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2038 argument is @code{nil}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2039
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2040 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
2041
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2042 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2043 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2044 default-directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2045 @result{} "/user/lewis/manual/"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2046 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2047 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2048 @end defvar
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2049
56215
c9aa4127a482 Reposition @anchor's.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56207
diff changeset
2050 @defun substitute-in-file-name filename
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2051 @anchor{Definition of substitute-in-file-name}
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2052 This function replaces environment variable references in
51793
ccbf5ac3316d (File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents: 51654
diff changeset
2053 @var{filename} with the environment variable values. Following
ccbf5ac3316d (File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents: 51654
diff changeset
2054 standard Unix shell syntax, @samp{$} is the prefix to substitute an
ccbf5ac3316d (File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents: 51654
diff changeset
2055 environment variable value. If the input contains @samp{$$}, that is
ccbf5ac3316d (File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents: 51654
diff changeset
2056 converted to @samp{$}; this gives the user a way to ``quote'' a
ccbf5ac3316d (File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents: 51654
diff changeset
2057 @samp{$}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2058
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2059 The environment variable name is the series of alphanumeric characters
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2060 (including underscores) that follow the @samp{$}. If the character following
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2061 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
2062 matching @samp{@}}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2063
51793
ccbf5ac3316d (File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents: 51654
diff changeset
2064 Calling @code{substitute-in-file-name} on output produced by
ccbf5ac3316d (File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents: 51654
diff changeset
2065 @code{substitute-in-file-name} tends to give incorrect results. For
ccbf5ac3316d (File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents: 51654
diff changeset
2066 instance, use of @samp{$$} to quote a single @samp{$} won't work
ccbf5ac3316d (File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents: 51654
diff changeset
2067 properly, and @samp{$} in an environment variable's value could lead
ccbf5ac3316d (File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents: 51654
diff changeset
2068 to repeated substitution. Therefore, programs that call this function
ccbf5ac3316d (File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents: 51654
diff changeset
2069 and put the output where it will be passed to this function need to
ccbf5ac3316d (File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents: 51654
diff changeset
2070 double all @samp{$} characters to prevent subsequent incorrect
ccbf5ac3316d (File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents: 51654
diff changeset
2071 results.
ccbf5ac3316d (File Name Expansion): Warn about iterative use of substitute-in-file-name.
Richard M. Stallman <rms@gnu.org>
parents: 51654
diff changeset
2072
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2073 @c Wordy to avoid overfull hbox. --rjc 15mar92
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2074 Here we assume that the environment variable @code{HOME}, which holds
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2075 the user's home directory name, has value @samp{/xcssun/users/rms}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2076
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2077 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2078 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2079 (substitute-in-file-name "$HOME/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2080 @result{} "/xcssun/users/rms/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2081 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2082 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2083
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2084 After substitution, if a @samp{~} or a @samp{/} appears immediately
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2085 after another @samp{/}, the function discards everything before it (up
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2086 through the immediately preceding @samp{/}).
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2087
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2088 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2089 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2090 (substitute-in-file-name "bar/~/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2091 @result{} "~/foo"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2092 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2093 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2094 (substitute-in-file-name "/usr/local/$HOME/foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2095 @result{} "/xcssun/users/rms/foo"
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2096 ;; @r{@file{/usr/local/} has been discarded.}
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2097 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2098 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2099
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2100 On VMS, @samp{$} substitution is not done, so this function does nothing
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2101 on VMS except discard superfluous initial components as shown above.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2102 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2103
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2104 @node Unique File Names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2105 @subsection Generating Unique File Names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2106
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2107 Some programs need to write temporary files. Here is the usual way to
60444
78a2cd972ba1 (Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 59877
diff changeset
2108 construct a name for such a file:
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2109
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2110 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2111 (make-temp-file @var{name-of-application})
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2112 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2113
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2114 @noindent
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2115 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
2116 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
2117
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2118 @defun make-temp-file prefix &optional dir-flag suffix
61795
8757023049af (Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents: 61793
diff changeset
2119 This function creates a temporary file and returns its name. Emacs
8757023049af (Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents: 61793
diff changeset
2120 creates the temporary file's name by adding to @var{prefix} some
8757023049af (Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents: 61793
diff changeset
2121 random characters that are different in each Emacs job. The result is
8757023049af (Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents: 61793
diff changeset
2122 guaranteed to be a newly created empty file. On MS-DOS, this function
8757023049af (Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents: 61793
diff changeset
2123 can truncate the @var{string} prefix to fit into the 8+3 file-name
8757023049af (Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents: 61793
diff changeset
2124 limits. If @var{prefix} is a relative file name, it is expanded
8757023049af (Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents: 61793
diff changeset
2125 against @code{temporary-file-directory}.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2126
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2127 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2128 @group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2129 (make-temp-file "foo")
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2130 @result{} "/tmp/foo232J6v"
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2131 @end group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2132 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2133
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2134 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
2135 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
2136 file.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2137
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2138 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2139 empty directory instead of an empty file. It returns the file name,
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2140 not the directory name, of that directory. @xref{Directory Names}.
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2141
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2142 If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2143 the end of the file name.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2144
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2145 To prevent conflicts among different libraries running in the same
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2146 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
2147 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
2148 distinguishes between the same application running in different Emacs
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2149 jobs. Additional added characters permit a large number of distinct
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2150 names even in one Emacs job.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2151 @end defun
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2152
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2153 The default directory for temporary files is controlled by the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2154 variable @code{temporary-file-directory}. This variable gives the user
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2155 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
2156 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
2157 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
2158 the proper directory before calling @code{make-temp-file}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2159
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2160 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
2161 you should use @code{make-temp-name} instead:
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2162
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2163 @example
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2164 (make-temp-name
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2165 (expand-file-name @var{name-of-application}
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2166 temporary-file-directory))
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2167 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2168
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2169 @defun make-temp-name string
61795
8757023049af (Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents: 61793
diff changeset
2170 This function generates a string that can be used as a unique file
8757023049af (Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents: 61793
diff changeset
2171 name. The name starts with @var{string}, and has several random
8757023049af (Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents: 61793
diff changeset
2172 characters appended to it, which are different in each Emacs job. It
8757023049af (Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents: 61793
diff changeset
2173 is like @code{make-temp-file} except that it just constructs a name,
8757023049af (Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents: 61793
diff changeset
2174 and does not create a file. Another difference is that @var{string}
8757023049af (Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents: 61793
diff changeset
2175 should be an absolute file name. On MS-DOS, this function can
8757023049af (Unique File Names): Don't mention "numbers" in the documentation
Eli Zaretskii <eliz@gnu.org>
parents: 61793
diff changeset
2176 truncate the @var{string} prefix to fit into the 8+3 file-name limits.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2177 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2178
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2179 @defvar temporary-file-directory
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2180 @cindex @code{TMPDIR} environment variable
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2181 @cindex @code{TMP} environment variable
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2182 @cindex @code{TEMP} environment variable
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2183 This variable specifies the directory name for creating temporary files.
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2184 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
2185 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
2186 name instead. Using the value as the second argument to
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2187 @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
2188
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2189 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
2190 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
2191 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
2192 none of these variables is defined.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2193
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2194 Even if you do not use @code{make-temp-file} to create the temporary
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2195 file, you should still use this variable to decide which directory to
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2196 put the file in. However, if you expect the file to be small, you
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2197 should use @code{small-temporary-file-directory} first if that is
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2198 non-@code{nil}.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2199 @end defvar
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2200
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2201 @defvar small-temporary-file-directory
60444
78a2cd972ba1 (Writing to Files): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 59877
diff changeset
2202 This variable specifies the directory name for
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2203 creating certain temporary files, which are likely to be small.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2204
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2205 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
2206 should compute the directory like this:
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2207
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2208 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2209 (make-temp-file
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2210 (expand-file-name @var{prefix}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2211 (or small-temporary-file-directory
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2212 temporary-file-directory)))
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2213 @end example
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2214 @end defvar
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2215
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2216 @node File Name Completion
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2217 @subsection File Name Completion
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2218 @cindex file name completion subroutines
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2219 @cindex completion, file name
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2220
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2221 This section describes low-level subroutines for completing a file
71489
dc87235a6d17 (File Name Completion): Point user to the node "Reading File Names".
Nick Roberts <nickrob@snap.net.nz>
parents: 71463
diff changeset
2222 name. For higher level functions, see @ref{Reading File Names}.
6555
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 @defun file-name-all-completions partial-filename directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2225 This function returns a list of all possible completions for a file
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2226 whose name starts with @var{partial-filename} in directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2227 @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
2228 in the directory, which is unpredictable and conveys no useful
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2229 information.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2230
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2231 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
2232 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
2233 buffer's default directory is prepended to @var{directory}, if
cda2b6ed6aec *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 28608
diff changeset
2234 @var{directory} is not absolute.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2235
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
2236 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
2237 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
2238 @file{foo}, @file{file~}, @file{file.c}, @file{file.c.~1~}, and
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2239 @file{file.c.~2~}.@refill
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2240
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2241 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2242 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2243 (file-name-all-completions "f" "")
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
2244 @result{} ("foo" "file~" "file.c.~2~"
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2245 "file.c.~1~" "file.c")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2246 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2247
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2248 @group
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
2249 (file-name-all-completions "fo" "")
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2250 @result{} ("foo")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2251 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2252 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2253 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2254
74688
29c73296a044 (File Name Completion): Document PREDICATE arg to file-name-completion.
Richard M. Stallman <rms@gnu.org>
parents: 71957
diff changeset
2255 @defun file-name-completion filename directory &optional predicate
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2256 This function completes the file name @var{filename} in directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2257 @var{directory}. It returns the longest prefix common to all file names
74688
29c73296a044 (File Name Completion): Document PREDICATE arg to file-name-completion.
Richard M. Stallman <rms@gnu.org>
parents: 71957
diff changeset
2258 in directory @var{directory} that start with @var{filename}. If
29c73296a044 (File Name Completion): Document PREDICATE arg to file-name-completion.
Richard M. Stallman <rms@gnu.org>
parents: 71957
diff changeset
2259 @var{predicate} is non-@code{nil} then it ignores possible completions
29c73296a044 (File Name Completion): Document PREDICATE arg to file-name-completion.
Richard M. Stallman <rms@gnu.org>
parents: 71957
diff changeset
2260 that don't satisfy @var{predicate}, after calling that function
29c73296a044 (File Name Completion): Document PREDICATE arg to file-name-completion.
Richard M. Stallman <rms@gnu.org>
parents: 71957
diff changeset
2261 with one argument, the expanded absolute file name.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2262
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2263 If only one match exists and @var{filename} matches it exactly, the
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2264 function returns @code{t}. The function returns @code{nil} if directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2265 @var{directory} contains no name starting with @var{filename}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2266
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2267 In the following example, suppose that the current default directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2268 has five files whose names begin with @samp{f}: @file{foo},
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2269 @file{file~}, @file{file.c}, @file{file.c.~1~}, and
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2270 @file{file.c.~2~}.@refill
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2271
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2272 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2273 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2274 (file-name-completion "fi" "")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2275 @result{} "file"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2276 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2277
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2278 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2279 (file-name-completion "file.c.~1" "")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2280 @result{} "file.c.~1~"
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2281 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2282
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2283 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2284 (file-name-completion "file.c.~1~" "")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2285 @result{} t
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2286 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2287
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2288 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2289 (file-name-completion "file.c.~3" "")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2290 @result{} nil
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2291 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2292 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2293 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2294
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2295 @defopt completion-ignored-extensions
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2296 @code{file-name-completion} usually ignores file names that end in any
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2297 string in this list. It does not ignore them when all the possible
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2298 completions end in one of these suffixes. This variable has no effect
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2299 on @code{file-name-all-completions}.@refill
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2300
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2301 A typical value might look like this:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2302
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2303 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2304 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2305 completion-ignored-extensions
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2306 @result{} (".o" ".elc" "~" ".dvi")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2307 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2308 @end example
39883
416c492df7c3 (File Name Completion): Document the significance of
Eli Zaretskii <eliz@gnu.org>
parents: 39296
diff changeset
2309
416c492df7c3 (File Name Completion): Document the significance of
Eli Zaretskii <eliz@gnu.org>
parents: 39296
diff changeset
2310 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
2311 @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
2312 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
2313 filter out a directory named @file{foo.elc}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2314 @end defopt
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2315
15765
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2316 @node Standard File Names
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2317 @subsection Standard File Names
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2318
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2319 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
2320 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
2321 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
2322 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
2323 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
2324 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
2325 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
2326 purposes.
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2327
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2328 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
2329 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
2330 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
2331 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
2332 @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
2333
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2334 @defun convert-standard-filename filename
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2335 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
2336 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
2337 @end defun
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2338
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2339 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
2340 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
2341 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
2342 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
2343 is an example from the @code{completion} package:
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2344
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2345 @example
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2346 (defvar save-completions-file-name
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2347 (convert-standard-filename "~/.completions")
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2348 "*The file name to save completions to.")
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2349 @end example
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2350
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2351 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
2352 @code{convert-standard-filename} returns its argument unchanged. On
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2353 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
2354
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2355 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
2356 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
2357 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
2358 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
2359 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
2360 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
2361 @file{.completions} becomes @file{_complet.ion}.
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2362
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2363 @node Contents of Directories
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2364 @section Contents of Directories
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2365 @cindex directory-oriented functions
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2366 @cindex file names in directory
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2367
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2368 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
2369 various names. Directories are a feature of the file system.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2370
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2371 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
2372 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
2373 the latter case, it can optionally display information about each file,
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2374 depending on the options passed to the @code{ls} command.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2375
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2376 @defun directory-files directory &optional full-name match-regexp nosort
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2377 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
2378 @var{directory}. By default, the list is in alphabetical order.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2379
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2380 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
2381 absolute file names. Otherwise, it returns the names relative to
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2382 the specified directory.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2383
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2384 If @var{match-regexp} is non-@code{nil}, this function returns only
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2385 those file names that contain a match for that regular expression---the
71463
f1944cae0a63 (Contents of Directories): Document case-insensitive behavior on respective
Eli Zaretskii <eliz@gnu.org>
parents: 71003
diff changeset
2386 other file names are excluded from the list. On case-insensitive
f1944cae0a63 (Contents of Directories): Document case-insensitive behavior on respective
Eli Zaretskii <eliz@gnu.org>
parents: 71003
diff changeset
2387 filesystems, the regular expression matching is case-insensitive.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2388
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2389 @c Emacs 19 feature
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2390 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
2391 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
2392 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
2393 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
2394 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
2395
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2396 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2397 @group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2398 (directory-files "~lewis")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2399 @result{} ("#foo#" "#foo.el#" "." ".."
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
2400 "dired-mods.el" "files.texi"
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2401 "files.texi.~1~")
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2402 @end group
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2403 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2404
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2405 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
2406 that can be read.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2407 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2408
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2409 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format
53425
bd30a9882e31 (Contents of Directories):
Richard M. Stallman <rms@gnu.org>
parents: 53109
diff changeset
2410 This is similar to @code{directory-files} in deciding which files
bd30a9882e31 (Contents of Directories):
Richard M. Stallman <rms@gnu.org>
parents: 53109
diff changeset
2411 to report on and how to report their names. However, instead
bd30a9882e31 (Contents of Directories):
Richard M. Stallman <rms@gnu.org>
parents: 53109
diff changeset
2412 of returning a list of file names, it returns for each file a
bd30a9882e31 (Contents of Directories):
Richard M. Stallman <rms@gnu.org>
parents: 53109
diff changeset
2413 list @code{(@var{filename} . @var{attributes})}, where @var{attributes}
bd30a9882e31 (Contents of Directories):
Richard M. Stallman <rms@gnu.org>
parents: 53109
diff changeset
2414 is what @code{file-attributes} would return for that file.
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2415 The optional argument @var{id-format} has the same meaning as the
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2416 corresponding argument to @code{file-attributes} (@pxref{Definition
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2417 of file-attributes}).
53425
bd30a9882e31 (Contents of Directories):
Richard M. Stallman <rms@gnu.org>
parents: 53109
diff changeset
2418 @end defun
bd30a9882e31 (Contents of Directories):
Richard M. Stallman <rms@gnu.org>
parents: 53109
diff changeset
2419
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2420 @defun file-name-all-versions file dirname
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2421 This function returns a list of all versions of the file named
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2422 @var{file} in directory @var{dirname}. It is only available on VMS.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2423 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2424
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2425 @defun file-expand-wildcards pattern &optional full
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2426 This function expands the wildcard pattern @var{pattern}, returning
24952
a6db4671c7a0 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24951
diff changeset
2427 a list of file names that match it.
24951
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2428
24952
a6db4671c7a0 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24951
diff changeset
2429 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
2430 the values are absolute also.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2431
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2432 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
2433 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
2434 normally also relative to the current default directory. However, if
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2435 @var{full} is non-@code{nil}, they are absolute.
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2436 @end defun
7451b1458af1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22271
diff changeset
2437
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2438 @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
2439 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
2440 directory @var{file}, formatted with @code{ls} according to
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2441 @var{switches}. It leaves point after the inserted text.
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2442 @var{switches} may be a string of options, or a list of strings
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2443 representing individual options.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2444
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2445 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
2446 specification including wildcard characters. If @var{wildcard} is
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2447 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
2448 wildcards.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2449
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
2450 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
2451 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
2452 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
2453 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
2454 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
2455 contents.)
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2456
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2457 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
2458 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
2459 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
2460 @code{shell-file-name}, to expand the wildcards.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2461
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2462 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
2463 @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
2464 with Lisp code.
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2465
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2466 As a technical detail, when @var{switches} contains the long
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2467 @samp{--dired} option, @code{insert-directory} treats it specially,
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2468 for the sake of dired. However, the normally equivalent short
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2469 @samp{-D} option is just passed on to @code{insert-directory-program},
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2470 as any other option.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2471 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2472
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2473 @defvar insert-directory-program
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2474 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
2475 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
2476 which generate the listing with Lisp code.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2477 @end defvar
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2478
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2479 @node Create/Delete Dirs
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2480 @section Creating and Deleting Directories
76841
fc9d442f98d2 Improve indexing.
Eli Zaretskii <eliz@gnu.org>
parents: 75476
diff changeset
2481 @cindex creating and deleting directories
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2482 @c Emacs 19 features
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2483
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2484 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
2485 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
2486 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
2487 delete directories.
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2488
26696
ef5e7bbe6f19 Current version from /gd/gnu/elisp.
Dave Love <fx@gnu.org>
parents: 25751
diff changeset
2489 @defun make-directory dirname &optional parents
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2490 This function creates a directory named @var{dirname}.
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2491 If @var{parents} is non-@code{nil}, as is always the case in an
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2492 interactive call, that means to create the parent directories first,
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2493 if they don't already exist.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2494 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2495
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2496 @defun delete-directory dirname
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2497 This function deletes the directory named @var{dirname}. The function
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2498 @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
2499 must use @code{delete-directory} for them. If the directory contains
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2500 any files, @code{delete-directory} signals an error.
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2501
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2502 This function only follows symbolic links at the level of parent
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2503 directories.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2504 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2505
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2506 @node Magic File Names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2507 @section Making Certain File Names ``Magic''
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2508 @cindex magic file names
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2509
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2510 @c Emacs 19 feature
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2511 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
2512 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
2513 feature is in implementing remote file names (@pxref{Remote Files,,
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2514 Remote Files, emacs, The GNU Emacs Manual}).
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2515
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2516 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
2517 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
2518 regular expression), plus a handler that implements all the primitive
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2519 Emacs file operations for file names that do match.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2520
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2521 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
2522 together with regular expressions that determine when to apply each
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2523 handler. Each element has this form:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2524
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2525 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2526 (@var{regexp} . @var{handler})
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2527 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2528
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2529 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2530 All the Emacs primitives for file access and file name transformation
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2531 check the given file name against @code{file-name-handler-alist}. If
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2532 the file name matches @var{regexp}, the primitives handle that file by
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2533 calling @var{handler}.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2534
61949
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2535 The first argument given to @var{handler} is the name of the
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2536 primitive, as a symbol; the remaining arguments are the arguments that
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2537 were passed to that primitive. (The first of these arguments is most
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2538 often the file name itself.) For example, if you do this:
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2539
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2540 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2541 (file-exists-p @var{filename})
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2542 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2543
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2544 @noindent
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2545 and @var{filename} has handler @var{handler}, then @var{handler} is
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2546 called like this:
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2547
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2548 @example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2549 (funcall @var{handler} 'file-exists-p @var{filename})
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2550 @end example
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2551
61949
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2552 When a function takes two or more arguments that must be file names,
37582
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2553 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
2554 this:
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2555
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2556 @example
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2557 (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
2558 @end example
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2559
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2560 @noindent
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2561 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
2562 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
2563 this:
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2564
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2565 @example
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2566 (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
2567 @end example
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2568
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2569 @noindent
fdf780ddf0ae Explain how handler is called, for magic file operations that take
Richard M. Stallman <rms@gnu.org>
parents: 32859
diff changeset
2570 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
2571 @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
2572
61949
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2573 If the specified file name matches more than one handler, the one
51913
3abc365e9d90 (Changing Files): copy-file allows dir as NEWNAME.
Richard M. Stallman <rms@gnu.org>
parents: 51793
diff changeset
2574 whose match starts last in the file name gets precedence. This rule
3abc365e9d90 (Changing Files): copy-file allows dir as NEWNAME.
Richard M. Stallman <rms@gnu.org>
parents: 51793
diff changeset
2575 is chosen so that handlers for jobs such as uncompression are handled
3abc365e9d90 (Changing Files): copy-file allows dir as NEWNAME.
Richard M. Stallman <rms@gnu.org>
parents: 51793
diff changeset
2576 first, before handlers for jobs such as remote file access.
3abc365e9d90 (Changing Files): copy-file allows dir as NEWNAME.
Richard M. Stallman <rms@gnu.org>
parents: 51793
diff changeset
2577
75476
330094c564c4 (File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
2578 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
2579
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
2580 @ifnottex
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2581 @noindent
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2582 @code{access-file}, @code{add-name-to-file},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2583 @code{byte-compiler-base-file-name},@*
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2584 @code{copy-file}, @code{delete-directory},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2585 @code{delete-file},
12226
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2586 @code{diff-latest-backup-file},
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2587 @code{directory-file-name},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2588 @code{directory-files},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2589 @code{directory-files-and-attributes},
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
2590 @code{dired-call-process},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2591 @code{dired-compress-file}, @code{dired-uncache},@*
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2592 @code{expand-file-name},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2593 @code{file-accessible-directory-p},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2594 @code{file-attributes},
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2595 @code{file-directory-p},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2596 @code{file-executable-p}, @code{file-exists-p},
55847
d87f8236b6fd files.texi (Magic File Names): Add `file-remote-p' as operation
Michael Albinus <michael.albinus@gmx.de>
parents: 55192
diff changeset
2597 @code{file-local-copy}, @code{file-remote-p},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2598 @code{file-modes}, @code{file-name-all-completions},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2599 @code{file-name-as-directory},
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2600 @code{file-name-completion},
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
2601 @code{file-name-directory},
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
2602 @code{file-name-nondirectory},
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2603 @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
2604 @code{file-ownership-preserved-p},
11626
0b86aef0c387 Mention file-regular-p operation.
Richard M. Stallman <rms@gnu.org>
parents: 8364
diff changeset
2605 @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
2606 @code{file-truename}, @code{file-writable-p},
15765
8cc15b664c4c New node Standard File Names.
Richard M. Stallman <rms@gnu.org>
parents: 14152
diff changeset
2607 @code{find-backup-file-name},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2608 @code{find-file-noselect},@*
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2609 @code{get-file-buffer},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2610 @code{insert-directory},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2611 @code{insert-file-contents},@*
65248
0f994edbec5e Make `make-auto-save-file-name' a magic operation.
Michael Albinus <michael.albinus@gmx.de>
parents: 64889
diff changeset
2612 @code{load},
0f994edbec5e Make `make-auto-save-file-name' a magic operation.
Michael Albinus <michael.albinus@gmx.de>
parents: 64889
diff changeset
2613 @code{make-auto-save-file-name},
0f994edbec5e Make `make-auto-save-file-name' a magic operation.
Michael Albinus <michael.albinus@gmx.de>
parents: 64889
diff changeset
2614 @code{make-directory},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2615 @code{make-directory-internal},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2616 @code{make-symbolic-link},@*
55192
dd5538a91d27 (Changing Files): Document set-file-times.
Eli Zaretskii <eliz@gnu.org>
parents: 54861
diff changeset
2617 @code{rename-file}, @code{set-file-modes}, @code{set-file-times},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2618 @code{set-visited-file-modtime}, @code{shell-command},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2619 @code{substitute-in-file-name},@*
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2620 @code{unhandled-file-name-directory},
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 15913
diff changeset
2621 @code{vc-registered},
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2622 @code{verify-visited-file-modtime},@*
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2623 @code{write-region}.
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
2624 @end ifnottex
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2625 @iftex
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2626 @noindent
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2627 @flushleft
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2628 @code{access-file}, @code{add-name-to-file},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2629 @code{byte-com@discretionary{}{}{}piler-base-file-name},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2630 @code{copy-file}, @code{delete-directory},
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2631 @code{delete-file},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2632 @code{diff-latest-backup-file},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2633 @code{directory-file-name},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2634 @code{directory-files},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2635 @code{directory-files-and-at@discretionary{}{}{}tributes},
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2636 @code{dired-call-process},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2637 @code{dired-compress-file}, @code{dired-uncache},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2638 @code{expand-file-name},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2639 @code{file-accessible-direc@discretionary{}{}{}tory-p},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2640 @code{file-attributes},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2641 @code{file-direct@discretionary{}{}{}ory-p},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2642 @code{file-executable-p}, @code{file-exists-p},
55847
d87f8236b6fd files.texi (Magic File Names): Add `file-remote-p' as operation
Michael Albinus <michael.albinus@gmx.de>
parents: 55192
diff changeset
2643 @code{file-local-copy}, @code{file-remote-p},
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2644 @code{file-modes}, @code{file-name-all-completions},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2645 @code{file-name-as-directory},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2646 @code{file-name-completion},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2647 @code{file-name-directory},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2648 @code{file-name-nondirec@discretionary{}{}{}tory},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2649 @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
2650 @code{file-ownership-pre@discretionary{}{}{}served-p},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2651 @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
2652 @code{file-truename}, @code{file-writable-p},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2653 @code{find-backup-file-name},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2654 @code{find-file-noselect},
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2655 @code{get-file-buffer},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2656 @code{insert-directory},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2657 @code{insert-file-contents},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2658 @code{load}, @code{make-direc@discretionary{}{}{}tory},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2659 @code{make-direc@discretionary{}{}{}tory-internal},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2660 @code{make-symbolic-link},
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2661 @code{rename-file}, @code{set-file-modes},
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2662 @code{set-visited-file-modtime}, @code{shell-command},
47980
5492d1831d2a From Michael Albinus.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 47514
diff changeset
2663 @code{substitute-in-file-name},
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2664 @code{unhandled-file-name-directory},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2665 @code{vc-regis@discretionary{}{}{}tered},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2666 @code{verify-visited-file-modtime},
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2667 @code{write-region}.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 24952
diff changeset
2668 @end flushleft
22271
71f954d59214 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
2669 @end iftex
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2670
61949
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2671 Handlers for @code{insert-file-contents} typically need to clear the
8118
56b5ed321f8d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2672 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
2673 @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
2674 unlocking the buffer if it is locked.
56b5ed321f8d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
2675
61949
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2676 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
2677 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
2678 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
2679 certain operation, it can reinvoke the primitive, to handle the
71957
61cb5aae3bc3 Put period and comma inside quotes.
Richard M. Stallman <rms@gnu.org>
parents: 71709
diff changeset
2680 operation ``in the usual way.'' It should always reinvoke the primitive
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7088
diff changeset
2681 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
2682
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2683 @smallexample
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2684 (defun my-file-handler (operation &rest args)
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2685 ;; @r{First check for the specific operations}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2686 ;; @r{that we have special handling for.}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2687 (cond ((eq operation 'insert-file-contents) @dots{})
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2688 ((eq operation 'write-region) @dots{})
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2689 @dots{}
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2690 ;; @r{Handle any operation we don't know about.}
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2691 (t (let ((inhibit-file-name-handlers
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 47980
diff changeset
2692 (cons 'my-file-handler
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2693 (and (eq inhibit-file-name-operation operation)
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2694 inhibit-file-name-handlers)))
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2695 (inhibit-file-name-operation operation))
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2696 (apply operation args)))))
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2697 @end smallexample
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2698
61949
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2699 When a handler function decides to call the ordinary Emacs primitive for
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2700 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
2701 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
2702 example above shows how to do this, with the variables
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2703 @code{inhibit-file-name-handlers} and
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2704 @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
2705 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
2706 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
2707 each have handlers.
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2708
51020
417a9e80f335 (Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents: 50501
diff changeset
2709 @kindex safe-magic (@r{property})
61949
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2710 Handlers that don't really do anything special for actual access to the
51020
417a9e80f335 (Magic File Names): Document the safe-magic property.
Richard M. Stallman <rms@gnu.org>
parents: 50501
diff changeset
2711 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
2712 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
2713 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
2714 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
2715 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
2716 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
2717 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
2718
61949
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2719 @kindex operations (@r{property})
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2720 A file name handler can have an @code{operations} property to
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2721 declare which operations it handles in a nontrivial way. If this
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2722 property has a non-@code{nil} value, it should be a list of
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2723 operations; then only those operations will call the handler. This
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2724 avoids inefficiency, but its main purpose is for autoloaded handler
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2725 functions, so that they won't be loaded except when they have real
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2726 work to do.
d0cfb9c978f9 (Magic File Names): Document `operations' property.
Richard M. Stallman <rms@gnu.org>
parents: 61795
diff changeset
2727
75476
330094c564c4 (File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
2728 Simply deferring all operations to the usual primitives does not
330094c564c4 (File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
2729 work. For instance, if the file name handler applies to
330094c564c4 (File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
2730 @code{file-exists-p}, then it must handle @code{load} itself, because
330094c564c4 (File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
2731 the usual @code{load} code won't work properly in that case. However,
330094c564c4 (File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
2732 if the handler uses the @code{operations} property to say it doesn't
330094c564c4 (File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
2733 handle @code{file-exists-p}, then it need not handle @code{load}
330094c564c4 (File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
2734 nontrivially.
330094c564c4 (File Attributes): UID and GID can be floats.
Richard M. Stallman <rms@gnu.org>
parents: 75250
diff changeset
2735
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2736 @defvar inhibit-file-name-handlers
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2737 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
2738 for a certain operation.
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2739 @end defvar
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2740
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2741 @defvar inhibit-file-name-operation
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2742 The operation for which certain handlers are presently inhibited.
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2743 @end defvar
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2744
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2745 @defun find-file-name-handler file operation
66737
09cf7401d368 (Magic File Names): find-file-name-handler checks the
Richard M. Stallman <rms@gnu.org>
parents: 66144
diff changeset
2746 This function returns the handler function for file name @var{file},
09cf7401d368 (Magic File Names): find-file-name-handler checks the
Richard M. Stallman <rms@gnu.org>
parents: 66144
diff changeset
2747 or @code{nil} if there is none. The argument @var{operation} should
09cf7401d368 (Magic File Names): find-file-name-handler checks the
Richard M. Stallman <rms@gnu.org>
parents: 66144
diff changeset
2748 be the operation to be performed on the file---the value you will pass
09cf7401d368 (Magic File Names): find-file-name-handler checks the
Richard M. Stallman <rms@gnu.org>
parents: 66144
diff changeset
2749 to the handler as its first argument when you call it. If
09cf7401d368 (Magic File Names): find-file-name-handler checks the
Richard M. Stallman <rms@gnu.org>
parents: 66144
diff changeset
2750 @var{operation} equals @code{inhibit-file-name-operation}, or if it is
09cf7401d368 (Magic File Names): find-file-name-handler checks the
Richard M. Stallman <rms@gnu.org>
parents: 66144
diff changeset
2751 not found in the @code{operations} property of the handler, this
09cf7401d368 (Magic File Names): find-file-name-handler checks the
Richard M. Stallman <rms@gnu.org>
parents: 66144
diff changeset
2752 function returns @code{nil}.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2753 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2754
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2755 @defun file-local-copy filename
52143
3b706f94b559 (Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents: 52003
diff changeset
2756 This function copies file @var{filename} to an ordinary non-magic file
3b706f94b559 (Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents: 52003
diff changeset
2757 on the local machine, if it isn't on the local machine already. Magic
3b706f94b559 (Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents: 52003
diff changeset
2758 file names should handle the @code{file-local-copy} operation if they
3b706f94b559 (Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents: 52003
diff changeset
2759 refer to files on other machines. A magic file name that is used for
3b706f94b559 (Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents: 52003
diff changeset
2760 other purposes than remote file access should not handle
3b706f94b559 (Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents: 52003
diff changeset
2761 @code{file-local-copy}; then this function will treat the file as
3b706f94b559 (Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents: 52003
diff changeset
2762 local.
3b706f94b559 (Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents: 52003
diff changeset
2763
3b706f94b559 (Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents: 52003
diff changeset
2764 If @var{filename} is local, whether magic or not, this function does
3b706f94b559 (Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents: 52003
diff changeset
2765 nothing and returns @code{nil}. Otherwise it returns the file name
3b706f94b559 (Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents: 52003
diff changeset
2766 of the local copy file.
3b706f94b559 (Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents: 52003
diff changeset
2767 @end defun
3b706f94b559 (Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents: 52003
diff changeset
2768
3b706f94b559 (Magic File Names): Add file-remote-p. Clarify file-local-copy.
Richard M. Stallman <rms@gnu.org>
parents: 52003
diff changeset
2769 @defun file-remote-p filename
56322
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
2770 This function tests whether @var{filename} is a remote file. If
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
2771 @var{filename} is local (not remote), the return value is @code{nil}.
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
2772 If @var{filename} is indeed remote, the return value is a string that
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
2773 identifies the remote system.
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
2774
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 62856
diff changeset
2775 This identifier string can include a host name and a user name, as
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 62856
diff changeset
2776 well as characters designating the method used to access the remote
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 62856
diff changeset
2777 system. For example, the remote identifier string for the filename
56322
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
2778 @code{/ssh:user@@host:/some/file} is @code{/ssh:user@@host:}.
56321
904bb1836ccd (Magic File Names): `file-remote-p' returns an identifier of the
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56231
diff changeset
2779
904bb1836ccd (Magic File Names): `file-remote-p' returns an identifier of the
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56231
diff changeset
2780 If @code{file-remote-p} returns the same identifier for two different
56322
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
2781 filenames, that means they are stored on the same file system and can
56321
904bb1836ccd (Magic File Names): `file-remote-p' returns an identifier of the
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 56231
diff changeset
2782 be accessed locally with respect to each other. This means, for
56322
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
2783 example, that it is possible to start a remote process accessing both
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
2784 files at the same time. Implementors of file handlers need to ensure
f597c982349e (Saving Buffers): Cleanup write-contents-function.
Richard M. Stallman <rms@gnu.org>
parents: 56321
diff changeset
2785 this principle is valid.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2786 @end defun
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2787
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2788 @defun unhandled-file-name-directory filename
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2789 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
2790 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
2791 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
2792 decides what value to return.
6555
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2793
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2794 This is useful for running a subprocess; every subprocess must have a
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2795 non-magic directory to serve as its current directory, and this function
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2796 is a good way to come up with one.
771fa0ddb356 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2797 @end defun
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2798
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2799 @node Format Conversion
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2800 @section File Format Conversion
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2801
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2802 @cindex file format conversion
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2803 @cindex encoding file formats
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2804 @cindex decoding file formats
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2805 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
2806 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
2807 text-properties, and possibly other information) in an Emacs buffer.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2808 Emacs performs format conversion if appropriate when reading and writing
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2809 files.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2810
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2811 @defvar format-alist
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2812 This list contains one format definition for each defined file format.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2813 @end defvar
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2814
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2815 @cindex format definition
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2816 Each format definition is a list of this form:
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2817
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2818 @example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2819 (@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
2820 @end example
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2821
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2822 Here is what the elements in a format definition mean:
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2823
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2824 @table @var
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2825 @item name
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2826 The name of this format.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2827
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2828 @item doc-string
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2829 A documentation string for the format.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2830
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2831 @item regexp
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2832 A regular expression which is used to recognize files represented in
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2833 this format.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2834
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2835 @item from-fn
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2836 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
2837 file data into the usual Emacs data representation).
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2838
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2839 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
2840 filter to perform the conversion.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2841
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2842 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
2843 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
2844 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
2845 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
2846 end position.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2847
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2848 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
2849 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
2850 get called again.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2851
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2852 @item to-fn
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2853 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
2854 convert the usual Emacs data representation into this format.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2855
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2856 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
2857 command as a filter to perform the conversion.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2858
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2859 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
2860 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
2861 There are two ways it can do the conversion:
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2862
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2863 @itemize @bullet
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2864 @item
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2865 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
2866 return the end-position of the range of text, as modified.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2867
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2868 @item
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2869 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
2870 form @code{(@var{position} . @var{string})}, where @var{position} is an
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2871 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
2872 @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
2873 order of position when @var{to-fn} returns it.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2874
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2875 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
2876 file, it intermixes the specified annotations at the corresponding
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2877 positions. All this takes place without modifying the buffer.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2878 @end itemize
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2879
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2880 @item modify
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2881 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
2882 @code{nil} if it works by returning a list of annotations.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2883
27259
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
2884 @item mode-fn
c41efa6c4be1 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
2885 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
2886 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
2887 that tells a minor-mode function to enable the mode.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2888 @end table
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2889
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2890 The function @code{insert-file-contents} automatically recognizes file
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2891 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
2892 beginning of the file against the regular expressions of the format
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2893 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
2894 that format. Then it checks all the known formats over again.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2895 It keeps checking them until none of them is applicable.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2896
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2897 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
2898 it, performs conversion likewise (because it calls
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2899 @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
2900 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
2901 buffer-local variable @code{buffer-file-format}.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2902
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2903 @defvar buffer-file-format
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2904 This variable states the format of the visited file. More precisely,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2905 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
2906 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
2907 buffers.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2908 @end defvar
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2909
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2910 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
2911 encoding functions for the formats listed in @code{buffer-file-format},
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
2912 in the order of appearance in the list.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2913
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2914 @deffn Command format-write-file file format &optional confirm
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2915 This command writes the current buffer contents into the file
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2916 @var{file} in format @var{format}, and makes that format the default
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2917 for future saves of the buffer. The argument @var{format} is a list
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2918 of format names. Except for the @var{format} argument, this command
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2919 is similar to @code{write-file}. In particular, @var{confirm} has the
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2920 same meaning and interactive treatment as the corresponding argument
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2921 to @code{write-file}. @xref{Definition of write-file}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2922 @end deffn
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2923
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2924 @deffn Command format-find-file file format
12226
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2925 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
2926 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
2927 buffer is saved later.
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2928
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2929 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
2930 @code{nil}, no conversion takes place. Interactively, typing just
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2931 @key{RET} for @var{format} specifies @code{nil}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2932 @end deffn
12226
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2933
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
2934 @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
2935 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
2936 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
2937 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
2938 @code{insert-file-contents} (@pxref{Reading from Files}).
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2939
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2940 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
2941 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
2942 (after conversion).
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2943
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2944 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
2945 @code{nil}, no conversion takes place. Interactively, typing just
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2946 @key{RET} for @var{format} specifies @code{nil}.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17919
diff changeset
2947 @end deffn
12226
af994773013b changes for 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
2948
56981
54f19dd158e9 (Format Conversion): `auto-save-file-format' has been renamed
Luc Teirlinck <teirllm@auburn.edu>
parents: 56322
diff changeset
2949 @defvar buffer-auto-save-file-format
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11626
diff changeset
2950 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
2951 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
2952 @code{buffer-file-format}; however, it is used instead of
54861
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2953 @code{buffer-file-format} for writing auto-save files. If the value
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2954 is @code{t}, the default, auto-saving uses the same format as a
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2955 regular save in the same buffer. This variable is always buffer-local
5af1398ad8e2 Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 54025
diff changeset
2956 in all buffers.
7088
5a93e6fb43a4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 6555
diff changeset
2957 @end defvar
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52143
diff changeset
2958
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52143
diff changeset
2959 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52143
diff changeset
2960 arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52143
diff changeset
2961 @end ignore