Mercurial > emacs
comparison lispref/files.texi @ 54861:5af1398ad8e2
Various changes in addition to:
(Visiting Functions): `find-file-hook' is now a normal hook.
(File Name Expansion): Explain difference between the way that
`expand-file-name' and `file-truename' treat `..'.
(Contents of Directories): Mention optional ID-FORMAT argument to
`directory-files-and-attributes'.
(Format Conversion): Mention new optional CONFIRM argument to
`format-write-file'.
author | Luc Teirlinck <teirllm@auburn.edu> |
---|---|
date | Wed, 14 Apr 2004 02:44:21 +0000 |
parents | 8659505a7f3d |
children | dd5538a91d27 |
comparison
equal
deleted
inserted
replaced
54860:8c5c95993ef5 | 54861:5af1398ad8e2 |
---|---|
93 @deffn Command find-file filename &optional wildcards | 93 @deffn Command find-file filename &optional wildcards |
94 This command selects a buffer visiting the file @var{filename}, | 94 This command selects a buffer visiting the file @var{filename}, |
95 using an existing buffer if there is one, and otherwise creating a | 95 using an existing buffer if there is one, and otherwise creating a |
96 new buffer and reading the file into it. It also returns that buffer. | 96 new buffer and reading the file into it. It also returns that buffer. |
97 | 97 |
98 The body of the @code{find-file} function is very simple and looks | 98 Aside from some technical details, the body of the @code{find-file} |
99 like this: | 99 function is basically equivalent to: |
100 | 100 |
101 @example | 101 @example |
102 (switch-to-buffer (find-file-noselect filename)) | 102 (switch-to-buffer (find-file-noselect filename nil nil wildcards)) |
103 @end example | 103 @end example |
104 | 104 |
105 @noindent | 105 @noindent |
106 (See @code{switch-to-buffer} in @ref{Displaying Buffers}.) | 106 (See @code{switch-to-buffer} in @ref{Displaying Buffers}.) |
107 | 107 |
191 When @code{view-file} is called interactively, it prompts for | 191 When @code{view-file} is called interactively, it prompts for |
192 @var{filename}. | 192 @var{filename}. |
193 @end deffn | 193 @end deffn |
194 | 194 |
195 @tindex find-file-wildcards | 195 @tindex find-file-wildcards |
196 @defvar find-file-wildcards | 196 @defopt find-file-wildcards |
197 If this variable is non-@code{nil}, then the various @code{find-file} | 197 If this variable is non-@code{nil}, then the various @code{find-file} |
198 commands check for wildcard characters and visit all the files that | 198 commands check for wildcard characters and visit all the files that |
199 match them. If this is @code{nil}, then wildcard characters are | 199 match them (when invoked interactively or when their @var{wildcards} |
200 not treated specially. | 200 argument is non-@code{nil}). If this option is @code{nil}, then |
201 @end defvar | 201 the @code{find-file} commands ignore their @var{wildcards} argument |
202 and never treat wildcard characters specially. | |
203 @end defopt | |
202 | 204 |
203 @defvar find-file-hook | 205 @defvar find-file-hook |
204 The value of this variable is a list of functions to be called after a | 206 The value of this variable is a list of functions to be called after a |
205 file is visited. The file's local-variables specification (if any) will | 207 file is visited. The file's local-variables specification (if any) will |
206 have been processed before the hooks are run. The buffer visiting the | 208 have been processed before the hooks are run. The buffer visiting the |
207 file is current when the hook functions are run. | 209 file is current when the hook functions are run. |
208 | 210 |
209 This variable works just like a normal hook, but we think that renaming | 211 This variable is a normal hook. @xref{Hooks}. |
210 it would not be advisable. @xref{Hooks}. | |
211 @end defvar | 212 @end defvar |
212 | 213 |
213 @defvar find-file-not-found-functions | 214 @defvar find-file-not-found-functions |
214 The value of this variable is a list of functions to be called when | 215 The value of this variable is a list of functions to be called when |
215 @code{find-file} or @code{find-file-noselect} is passed a nonexistent | 216 @code{find-file} or @code{find-file-noselect} is passed a nonexistent |
320 | 321 |
321 @item | 322 @item |
322 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the | 323 With an argument of 16 or 64, reflecting 2 or 3 @kbd{C-u}'s, the |
323 @code{save-buffer} function unconditionally backs up the previous | 324 @code{save-buffer} function unconditionally backs up the previous |
324 version of the file before saving it. | 325 version of the file before saving it. |
326 | |
327 @item | |
328 With an argument of 0, unconditionally do @emph{not} make any backup file. | |
325 @end itemize | 329 @end itemize |
326 @end deffn | 330 @end deffn |
327 | 331 |
332 @anchor{Definition of save-some-buffers} | |
328 @deffn Command save-some-buffers &optional save-silently-p pred | 333 @deffn Command save-some-buffers &optional save-silently-p pred |
329 This command saves some modified file-visiting buffers. Normally it | 334 This command saves some modified file-visiting buffers. Normally it |
330 asks the user about each buffer. But if @var{save-silently-p} is | 335 asks the user about each buffer. But if @var{save-silently-p} is |
331 non-@code{nil}, it saves all the file-visiting buffers without querying | 336 non-@code{nil}, it saves all the file-visiting buffers without querying |
332 the user. | 337 the user. |
333 | 338 |
334 The optional @var{pred} argument controls which buffers to ask about. | 339 The optional @var{pred} argument controls which buffers to ask about |
340 (or to save silently if @var{save-silently-p} is non-@code{nil}). | |
335 If it is @code{nil}, that means to ask only about file-visiting buffers. | 341 If it is @code{nil}, that means to ask only about file-visiting buffers. |
336 If it is @code{t}, that means also offer to save certain other non-file | 342 If it is @code{t}, that means also offer to save certain other non-file |
337 buffers---those that have a non-@code{nil} buffer-local value of | 343 buffers---those that have a non-@code{nil} buffer-local value of |
338 @code{buffer-offer-save}. (A user who says @samp{yes} to saving a | 344 @code{buffer-offer-save}. (A user who says @samp{yes} to saving a |
339 non-file buffer is asked to specify the file name to use.) The | 345 non-file buffer is asked to specify the file name to use.) The |
344 a function of no arguments. It will be called in each buffer to decide | 350 a function of no arguments. It will be called in each buffer to decide |
345 whether to offer to save that buffer. If it returns a non-@code{nil} | 351 whether to offer to save that buffer. If it returns a non-@code{nil} |
346 value in a certain buffer, that means do offer to save that buffer. | 352 value in a certain buffer, that means do offer to save that buffer. |
347 @end deffn | 353 @end deffn |
348 | 354 |
355 @anchor{Definition of write-file} | |
349 @deffn Command write-file filename &optional confirm | 356 @deffn Command write-file filename &optional confirm |
350 This function writes the current buffer into file @var{filename}, makes | 357 This function writes the current buffer into file @var{filename}, makes |
351 the buffer visit that file, and marks it not modified. Then it renames | 358 the buffer visit that file, and marks it not modified. Then it renames |
352 the buffer based on @var{filename}, appending a string like @samp{<2>} | 359 the buffer based on @var{filename}, appending a string like @samp{<2>} |
353 if necessary to make a unique buffer name. It does most of this work by | 360 if necessary to make a unique buffer name. It does most of this work by |
354 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and | 361 calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and |
355 @code{save-buffer}. | 362 @code{save-buffer}. |
356 | 363 |
357 If @var{confirm} is non-@code{nil}, that means to ask for confirmation | 364 If @var{confirm} is non-@code{nil}, that means to ask for confirmation |
358 before overwriting an existing file. | 365 before overwriting an existing file. Interactively, confirmation is |
366 required, unless the user supplies a prefix argument. | |
367 | |
368 If @var{filename} is an existing directory, or a symbolic link to one, | |
369 @code{write-file} uses the name of the visited file, in directory | |
370 @var{filename}. If the buffer is not visiting a file, it uses the | |
371 buffer name instead. | |
359 @end deffn | 372 @end deffn |
360 | 373 |
361 Saving a buffer runs several hooks. It also performs format | 374 Saving a buffer runs several hooks. It also performs format |
362 conversion (@pxref{Format Conversion}), and may save text properties in | 375 conversion (@pxref{Format Conversion}), and may save text properties in |
363 ``annotations'' (@pxref{Saving Properties}). | 376 ``annotations'' (@pxref{Saving Properties}). |
376 @example | 389 @example |
377 (or buffer-backed-up (backup-buffer)) | 390 (or buffer-backed-up (backup-buffer)) |
378 @end example | 391 @end example |
379 | 392 |
380 You might wish to save the file modes value returned by | 393 You might wish to save the file modes value returned by |
381 @code{backup-buffer} and use that to set the mode bits of the file that | 394 @code{backup-buffer} and use that (if non-@code{nil}) to set the mode |
382 you write. This is what @code{save-buffer} normally does. | 395 bits of the file that you write. This is what @code{save-buffer} |
396 normally does. @xref{Making Backups,, Making Backup Files}. | |
383 | 397 |
384 The hook functions in @code{write-file-functions} are also responsible for | 398 The hook functions in @code{write-file-functions} are also responsible for |
385 encoding the data (if desired): they must choose a suitable coding | 399 encoding the data (if desired): they must choose a suitable coding |
386 system (@pxref{Lisp and Coding Systems}), perform the encoding | 400 system (@pxref{Lisp and Coding Systems}), perform the encoding |
387 (@pxref{Explicit Encoding}), and set @code{last-coding-system-used} to | 401 (@pxref{Explicit Encoding}), and set @code{last-coding-system-used} to |
426 This normal hook runs after a buffer has been saved in its visited file. | 440 This normal hook runs after a buffer has been saved in its visited file. |
427 One use of this hook is in Fast Lock mode; it uses this hook to save the | 441 One use of this hook is in Fast Lock mode; it uses this hook to save the |
428 highlighting information in a cache file. | 442 highlighting information in a cache file. |
429 @end defopt | 443 @end defopt |
430 | 444 |
431 @defvar file-precious-flag | 445 @defopt file-precious-flag |
432 If this variable is non-@code{nil}, then @code{save-buffer} protects | 446 If this variable is non-@code{nil}, then @code{save-buffer} protects |
433 against I/O errors while saving by writing the new file to a temporary | 447 against I/O errors while saving by writing the new file to a temporary |
434 name instead of the name it is supposed to have, and then renaming it to | 448 name instead of the name it is supposed to have, and then renaming it to |
435 the intended name after it is clear there are no errors. This procedure | 449 the intended name after it is clear there are no errors. This procedure |
436 prevents problems such as a lack of disk space from resulting in an | 450 prevents problems such as a lack of disk space from resulting in an |
440 or Copy}. Yet, at the same time, saving a precious file always breaks | 454 or Copy}. Yet, at the same time, saving a precious file always breaks |
441 all hard links between the file you save and other file names. | 455 all hard links between the file you save and other file names. |
442 | 456 |
443 Some modes give this variable a non-@code{nil} buffer-local value | 457 Some modes give this variable a non-@code{nil} buffer-local value |
444 in particular buffers. | 458 in particular buffers. |
445 @end defvar | 459 @end defopt |
446 | 460 |
447 @defopt require-final-newline | 461 @defopt require-final-newline |
448 This variable determines whether files may be written out that do | 462 This variable determines whether files may be written out that do |
449 @emph{not} end with a newline. If the value of the variable is | 463 @emph{not} end with a newline. If the value of the variable is |
450 @code{t}, then @code{save-buffer} silently adds a newline at the end of | 464 @code{t}, then @code{save-buffer} silently adds a newline at the end of |
539 @var{filename}. If that file does not exist, it is created. This | 553 @var{filename}. If that file does not exist, it is created. This |
540 function returns @code{nil}. | 554 function returns @code{nil}. |
541 | 555 |
542 An error is signaled if @var{filename} specifies a nonwritable file, | 556 An error is signaled if @var{filename} specifies a nonwritable file, |
543 or a nonexistent file in a directory where files cannot be created. | 557 or a nonexistent file in a directory where files cannot be created. |
558 | |
559 When called from Lisp, this function is completely equivalent to: | |
560 | |
561 @example | |
562 (write-region start end filename t) | |
563 @end example | |
544 @end deffn | 564 @end deffn |
545 | 565 |
546 @deffn Command write-region start end filename &optional append visit lockname mustbenew | 566 @deffn Command write-region start end filename &optional append visit lockname mustbenew |
547 This function writes the region delimited by @var{start} and @var{end} | 567 This function writes the region delimited by @var{start} and @var{end} |
548 in the current buffer into the file specified by @var{filename}. | 568 in the current buffer into the file specified by @var{filename}. |
569 | |
570 If @var{start} is @code{nil}, then the command writes the entire buffer | |
571 contents (@emph{not} just the accessible portion) to the file and | |
572 ignores @var{end}. | |
549 | 573 |
550 @c Emacs 19 feature | 574 @c Emacs 19 feature |
551 If @var{start} is a string, then @code{write-region} writes or appends | 575 If @var{start} is a string, then @code{write-region} writes or appends |
552 that string, rather than text from the buffer. @var{end} is ignored in | 576 that string, rather than text from the buffer. @var{end} is ignored in |
553 this case. | 577 this case. |
599 nor @code{nil} nor a string, then this message is inhibited. This | 623 nor @code{nil} nor a string, then this message is inhibited. This |
600 feature is useful for programs that use files for internal purposes, | 624 feature is useful for programs that use files for internal purposes, |
601 files that the user does not need to know about. | 625 files that the user does not need to know about. |
602 @end deffn | 626 @end deffn |
603 | 627 |
628 @anchor{Definition of with-temp-file} | |
604 @defmac with-temp-file file body... | 629 @defmac with-temp-file file body... |
605 The @code{with-temp-file} macro evaluates the @var{body} forms with a | 630 The @code{with-temp-file} macro evaluates the @var{body} forms with a |
606 temporary buffer as the current buffer; then, at the end, it writes the | 631 temporary buffer as the current buffer; then, at the end, it writes the |
607 buffer contents into file @var{file}. It kills the temporary buffer | 632 buffer contents into file @var{file}. It kills the temporary buffer |
608 when finished, restoring the buffer that was current before the | 633 when finished, restoring the buffer that was current before the |
610 in @var{body}. | 635 in @var{body}. |
611 | 636 |
612 The current buffer is restored even in case of an abnormal exit via | 637 The current buffer is restored even in case of an abnormal exit via |
613 @code{throw} or error (@pxref{Nonlocal Exits}). | 638 @code{throw} or error (@pxref{Nonlocal Exits}). |
614 | 639 |
615 See also @code{with-temp-buffer} in @ref{Current Buffer}. | 640 See also @code{with-temp-buffer} in @ref{Definition of |
641 with-temp-buffer,, The Current Buffer}. | |
616 @end defmac | 642 @end defmac |
617 | 643 |
618 @node File Locks | 644 @node File Locks |
619 @section File Locks | 645 @section File Locks |
620 @cindex file locks | 646 @cindex file locks |
723 @comment node-name, next, previous, up | 749 @comment node-name, next, previous, up |
724 @subsection Testing Accessibility | 750 @subsection Testing Accessibility |
725 @cindex accessibility of a file | 751 @cindex accessibility of a file |
726 @cindex file accessibility | 752 @cindex file accessibility |
727 | 753 |
728 These functions test for permission to access a file in specific ways. | 754 These functions test for permission to access a file in specific |
755 ways. Unless explicitly stated otherwise, they recursively follow | |
756 symbolic links for their file name arguments, at all levels (at the | |
757 level of the file itself and at all levels of parent directories). | |
729 | 758 |
730 @defun file-exists-p filename | 759 @defun file-exists-p filename |
731 This function returns @code{t} if a file named @var{filename} appears | 760 This function returns @code{t} if a file named @var{filename} appears |
732 to exist. This does not mean you can necessarily read the file, only | 761 to exist. This does not mean you can necessarily read the file, only |
733 that you can find out its attributes. (On Unix and GNU/Linux, this is | 762 that you can find out its attributes. (On Unix and GNU/Linux, this is |
827 using @var{string} as the error message text. | 856 using @var{string} as the error message text. |
828 @end defun | 857 @end defun |
829 | 858 |
830 @defun file-ownership-preserved-p filename | 859 @defun file-ownership-preserved-p filename |
831 This function returns @code{t} if deleting the file @var{filename} and | 860 This function returns @code{t} if deleting the file @var{filename} and |
832 then creating it anew would keep the file's owner unchanged. | 861 then creating it anew would keep the file's owner unchanged. It also |
862 returns @code{t} for nonexistent files. | |
863 | |
864 If @var{filename} is a symbolic link, then, unlike the other functions | |
865 discussed here, @code{file-ownership-preserved-p} does @emph{not} | |
866 replace @var{filename} with its target. However, it does recursively | |
867 follow symbolic links at all levels of parent directories. | |
833 @end defun | 868 @end defun |
834 | 869 |
835 @defun file-newer-than-file-p filename1 filename2 | 870 @defun file-newer-than-file-p filename1 filename2 |
836 @cindex file age | 871 @cindex file age |
837 @cindex file modification time | 872 @cindex file modification time |
838 This function returns @code{t} if the file @var{filename1} is | 873 This function returns @code{t} if the file @var{filename1} is |
839 newer than file @var{filename2}. If @var{filename1} does not | 874 newer than file @var{filename2}. If @var{filename1} does not |
840 exist, it returns @code{nil}. If @var{filename2} does not exist, | 875 exist, it returns @code{nil}. If @var{filename1} does exist, but |
841 it returns @code{t}. | 876 @var{filename2} does not, it returns @code{t}. |
842 | 877 |
843 In the following example, assume that the file @file{aug-19} was written | 878 In the following example, assume that the file @file{aug-19} was written |
844 on the 19th, @file{aug-20} was written on the 20th, and the file | 879 on the 19th, @file{aug-20} was written on the 20th, and the file |
845 @file{no-file} doesn't exist at all. | 880 @file{no-file} doesn't exist at all. |
846 | 881 |
875 as directories, symbolic links, and ordinary files. | 910 as directories, symbolic links, and ordinary files. |
876 | 911 |
877 @defun file-symlink-p filename | 912 @defun file-symlink-p filename |
878 @cindex file symbolic links | 913 @cindex file symbolic links |
879 If the file @var{filename} is a symbolic link, the | 914 If the file @var{filename} is a symbolic link, the |
880 @code{file-symlink-p} function returns the link target as a string. | 915 @code{file-symlink-p} function returns the (non-recursive) link target |
881 (Determining the file name that the link points to from the target is | 916 as a string. (Determining the file name that the link points to from |
882 nontrivial.) | 917 the target is nontrivial.) First, this function recursively follows |
918 symbolic links at all levels of parent directories. | |
883 | 919 |
884 If the file @var{filename} is not a symbolic link (or there is no such file), | 920 If the file @var{filename} is not a symbolic link (or there is no such file), |
885 @code{file-symlink-p} returns @code{nil}. | 921 @code{file-symlink-p} returns @code{nil}. |
886 | 922 |
887 @example | 923 @example |
903 @end group | 939 @end group |
904 @end example | 940 @end example |
905 | 941 |
906 @c !!! file-symlink-p: should show output of ls -l for comparison | 942 @c !!! file-symlink-p: should show output of ls -l for comparison |
907 @end defun | 943 @end defun |
944 | |
945 The next two functions recursively follow symbolic links at | |
946 all levels for @var{filename}. | |
908 | 947 |
909 @defun file-directory-p filename | 948 @defun file-directory-p filename |
910 This function returns @code{t} if @var{filename} is the name of an | 949 This function returns @code{t} if @var{filename} is the name of an |
911 existing directory, @code{nil} otherwise. | 950 existing directory, @code{nil} otherwise. |
912 | 951 |
955 because they eliminate symbolic links as a cause of name variation. | 994 because they eliminate symbolic links as a cause of name variation. |
956 | 995 |
957 @defun file-truename filename | 996 @defun file-truename filename |
958 The function @code{file-truename} returns the truename of the file | 997 The function @code{file-truename} returns the truename of the file |
959 @var{filename}. The argument must be an absolute file name. | 998 @var{filename}. The argument must be an absolute file name. |
999 | |
1000 This function does not expand environment variables. Only | |
1001 @code{substitute-in-file-name} does that. @xref{Definition of | |
1002 substitute-in-file-name}. | |
1003 | |
1004 If you may need to follow symbolic links preceding @samp{..}@: | |
1005 appearing as a name component, you should make sure to call | |
1006 @code{file-truename} without prior direct or indirect calls to | |
1007 @code{expand-file-name}, as otherwise the file name component | |
1008 immediately preceding @samp{..} will be ``simplified away'' before | |
1009 @code{file-truename} is called. To eliminate the need for a call to | |
1010 @code{expand-file-name}, @code{file-truename} handles @samp{~} in the | |
1011 same way that @code{expand-file-name} does. @xref{File Name | |
1012 Expansion,, Functions that Expand Filenames}. | |
960 @end defun | 1013 @end defun |
961 | 1014 |
962 @defun file-chase-links filename &optional limit | 1015 @defun file-chase-links filename &optional limit |
963 This function follows symbolic links, starting with @var{filename}, | 1016 This function follows symbolic links, starting with @var{filename}, |
964 until it finds a file name which is not the name of a symbolic link. | 1017 until it finds a file name which is not the name of a symbolic link. |
965 Then it returns that file name. If you specify a number for | 1018 Then it returns that file name. This function does @emph{not} follow |
966 @var{limit}, then after chasing through that many links, the function | 1019 symbolic links at the level of parent directories. |
967 just returns what it as even if that is still a symbolic link. | 1020 |
1021 If you specify a number for @var{limit}, then after chasing through | |
1022 that many links, the function just returns what it has even if that is | |
1023 still a symbolic link. | |
968 @end defun | 1024 @end defun |
969 | 1025 |
970 To illustrate the difference between @code{file-chase-links} and | 1026 To illustrate the difference between @code{file-chase-links} and |
971 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to | 1027 @code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to |
972 the directory @file{/home/foo}, and @file{/home/foo/hello} is an | 1028 the directory @file{/home/foo}, and @file{/home/foo/hello} is an |
1005 | 1061 |
1006 The highest value returnable is 4095 (7777 octal), meaning that | 1062 The highest value returnable is 4095 (7777 octal), meaning that |
1007 everyone has read, write, and execute permission, that the @acronym{SUID} bit | 1063 everyone has read, write, and execute permission, that the @acronym{SUID} bit |
1008 is set for both others and group, and that the sticky bit is set. | 1064 is set for both others and group, and that the sticky bit is set. |
1009 | 1065 |
1066 If @var{filename} does not exist, @code{file-modes} returns @code{nil}. | |
1067 | |
1068 This function recursively follows symbolic links at all levels. | |
1069 | |
1010 @example | 1070 @example |
1011 @group | 1071 @group |
1012 (file-modes "~/junk/diffs") | 1072 (file-modes "~/junk/diffs") |
1013 @result{} 492 ; @r{Decimal integer.} | 1073 @result{} 492 ; @r{Decimal integer.} |
1014 @end group | 1074 @end group |
1031 % ls -l diffs | 1091 % ls -l diffs |
1032 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs | 1092 -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs |
1033 @end group | 1093 @end group |
1034 @end example | 1094 @end example |
1035 @end defun | 1095 @end defun |
1096 | |
1097 If the @var{filename} argument to the next two functions is a symbolic | |
1098 link, then these function do @emph{not} replace it with its target. | |
1099 However, they both recursively follow symbolic links at all levels of | |
1100 parent directories. | |
1036 | 1101 |
1037 @defun file-nlinks filename | 1102 @defun file-nlinks filename |
1038 This functions returns the number of names (i.e., hard links) that | 1103 This functions returns the number of names (i.e., hard links) that |
1039 file @var{filename} has. If the file does not exist, then this function | 1104 file @var{filename} has. If the file does not exist, then this function |
1040 returns @code{nil}. Note that symbolic links have no effect on this | 1105 returns @code{nil}. Note that symbolic links have no effect on this |
1057 @result{} nil | 1122 @result{} nil |
1058 @end group | 1123 @end group |
1059 @end example | 1124 @end example |
1060 @end defun | 1125 @end defun |
1061 | 1126 |
1127 @anchor{Definition of file-attributes} | |
1062 @defun file-attributes filename &optional id-format | 1128 @defun file-attributes filename &optional id-format |
1063 This function returns a list of attributes of file @var{filename}. If | 1129 This function returns a list of attributes of file @var{filename}. If |
1064 the specified file cannot be opened, it returns @code{nil}. | 1130 the specified file cannot be opened, it returns @code{nil}. |
1065 The optional parameter @var{id-format} specifies the preferred format | 1131 The optional parameter @var{id-format} specifies the preferred format |
1066 of attributes @acronym{UID} and @acronym{GID} (see below)---the | 1132 of attributes @acronym{UID} and @acronym{GID} (see below)---the |
1211 @item | 1277 @item |
1212 Replace the old file without confirmation if @var{ok-if-already-exists} | 1278 Replace the old file without confirmation if @var{ok-if-already-exists} |
1213 is any other value. | 1279 is any other value. |
1214 @end itemize | 1280 @end itemize |
1215 | 1281 |
1216 @defun add-name-to-file oldname newname &optional ok-if-already-exists | 1282 The next four commands all recursively follow symbolic links at all |
1283 levels of parent directories for their first argument, but, if that | |
1284 argument is itself a symbolic link, then only @code{copy-file} | |
1285 replaces it with its (recursive) target. | |
1286 | |
1287 @deffn Command add-name-to-file oldname newname &optional ok-if-already-exists | |
1217 @cindex file with multiple names | 1288 @cindex file with multiple names |
1218 @cindex file hard link | 1289 @cindex file hard link |
1219 This function gives the file named @var{oldname} the additional name | 1290 This function gives the file named @var{oldname} the additional name |
1220 @var{newname}. This means that @var{newname} becomes a new ``hard | 1291 @var{newname}. This means that @var{newname} becomes a new ``hard |
1221 link'' to @var{oldname}. | 1292 link'' to @var{oldname}. |
1277 This function is meaningless on operating systems where multiple names | 1348 This function is meaningless on operating systems where multiple names |
1278 for one file are not allowed. Some systems implement multiple names | 1349 for one file are not allowed. Some systems implement multiple names |
1279 by copying the file instead. | 1350 by copying the file instead. |
1280 | 1351 |
1281 See also @code{file-nlinks} in @ref{File Attributes}. | 1352 See also @code{file-nlinks} in @ref{File Attributes}. |
1282 @end defun | 1353 @end deffn |
1283 | 1354 |
1284 @deffn Command rename-file filename newname &optional ok-if-already-exists | 1355 @deffn Command rename-file filename newname &optional ok-if-already-exists |
1285 This command renames the file @var{filename} as @var{newname}. | 1356 This command renames the file @var{filename} as @var{newname}. |
1286 | 1357 |
1287 If @var{filename} has additional names aside from @var{filename}, it | 1358 If @var{filename} has additional names aside from @var{filename}, it |
1288 continues to have those names. In fact, adding the name @var{newname} | 1359 continues to have those names. In fact, adding the name @var{newname} |
1289 with @code{add-name-to-file} and then deleting @var{filename} has the | 1360 with @code{add-name-to-file} and then deleting @var{filename} has the |
1290 same effect as renaming, aside from momentary intermediate states. | 1361 same effect as renaming, aside from momentary intermediate states. |
1291 | |
1292 In an interactive call, this function prompts for @var{filename} and | |
1293 @var{newname} in the minibuffer; also, it requests confirmation if | |
1294 @var{newname} already exists. | |
1295 @end deffn | 1362 @end deffn |
1296 | 1363 |
1297 @deffn Command copy-file oldname newname &optional ok-if-exists time | 1364 @deffn Command copy-file oldname newname &optional ok-if-exists time |
1298 This command copies the file @var{oldname} to @var{newname}. An | 1365 This command copies the file @var{oldname} to @var{newname}. An |
1299 error is signaled if @var{oldname} does not exist. If @var{newname} | 1366 error is signaled if @var{oldname} does not exist. If @var{newname} |
1305 some operating systems.) If setting the time gets an error, | 1372 some operating systems.) If setting the time gets an error, |
1306 @code{copy-file} signals a @code{file-date-error} error. | 1373 @code{copy-file} signals a @code{file-date-error} error. |
1307 | 1374 |
1308 This function copies the file modes, too. | 1375 This function copies the file modes, too. |
1309 | 1376 |
1310 In an interactive call, this function prompts for @var{filename} and | 1377 In an interactive call, a prefix argument specifies a non-@code{nil} |
1311 @var{newname} in the minibuffer; also, it requests confirmation if | 1378 value for @var{time}. |
1312 @var{newname} already exists. | |
1313 @end deffn | |
1314 | |
1315 @deffn Command delete-file filename | |
1316 @pindex rm | |
1317 This command deletes the file @var{filename}, like the shell command | |
1318 @samp{rm @var{filename}}. If the file has multiple names, it continues | |
1319 to exist under the other names. | |
1320 | |
1321 A suitable kind of @code{file-error} error is signaled if the file does | |
1322 not exist, or is not deletable. (On Unix and GNU/Linux, a file is | |
1323 deletable if its directory is writable.) | |
1324 | |
1325 See also @code{delete-directory} in @ref{Create/Delete Dirs}. | |
1326 @end deffn | 1379 @end deffn |
1327 | 1380 |
1328 @deffn Command make-symbolic-link filename newname &optional ok-if-exists | 1381 @deffn Command make-symbolic-link filename newname &optional ok-if-exists |
1329 @pindex ln | 1382 @pindex ln |
1330 @kindex file-already-exists | 1383 @kindex file-already-exists |
1331 This command makes a symbolic link to @var{filename}, named | 1384 This command makes a symbolic link to @var{filename}, named |
1332 @var{newname}. This is like the shell command @samp{ln -s | 1385 @var{newname}. This is like the shell command @samp{ln -s |
1333 @var{filename} @var{newname}}. | 1386 @var{filename} @var{newname}}. |
1334 | 1387 |
1335 In an interactive call, this function prompts for @var{filename} and | |
1336 @var{newname} in the minibuffer; also, it requests confirmation if | |
1337 @var{newname} already exists. | |
1338 | |
1339 This function is not available on systems that don't support symbolic | 1388 This function is not available on systems that don't support symbolic |
1340 links. | 1389 links. |
1341 @end deffn | 1390 @end deffn |
1342 | 1391 |
1392 @deffn Command delete-file filename | |
1393 @pindex rm | |
1394 This command deletes the file @var{filename}, like the shell command | |
1395 @samp{rm @var{filename}}. If the file has multiple names, it continues | |
1396 to exist under the other names. | |
1397 | |
1398 A suitable kind of @code{file-error} error is signaled if the file does | |
1399 not exist, or is not deletable. (On Unix and GNU/Linux, a file is | |
1400 deletable if its directory is writable.) | |
1401 | |
1402 If @var{filename} is a symbolic link, @code{delete-file} does not | |
1403 replace it with its target, but it does follow symbolic links at all | |
1404 levels of parent directories. | |
1405 | |
1406 See also @code{delete-directory} in @ref{Create/Delete Dirs}. | |
1407 @end deffn | |
1408 | |
1343 @defun define-logical-name varname string | 1409 @defun define-logical-name varname string |
1344 This function defines the logical name @var{varname} to have the value | 1410 This function defines the logical name @var{varname} to have the value |
1345 @var{string}. It is available only on VMS. | 1411 @var{string}. It is available only on VMS. |
1346 @end defun | 1412 @end defun |
1347 | 1413 |
1348 @defun set-file-modes filename mode | 1414 @defun set-file-modes filename mode |
1349 This function sets mode bits of @var{filename} to @var{mode} (which must | 1415 This function sets mode bits of @var{filename} to @var{mode} (which |
1350 be an integer). Only the low 12 bits of @var{mode} are used. | 1416 must be an integer). Only the low 12 bits of @var{mode} are used. |
1417 This function recursively follows symbolic links at all levels for | |
1418 @var{filename}. | |
1351 @end defun | 1419 @end defun |
1352 | 1420 |
1353 @c Emacs 19 feature | 1421 @c Emacs 19 feature |
1354 @defun set-default-file-modes mode | 1422 @defun set-default-file-modes mode |
1355 @cindex umask | 1423 @cindex umask |
1498 @result{} "FOO.TMP" | 1566 @result{} "FOO.TMP" |
1499 @end group | 1567 @end group |
1500 @end example | 1568 @end example |
1501 @end defun | 1569 @end defun |
1502 | 1570 |
1503 @defun file-name-extension filename &optional period | |
1504 This function returns @var{filename}'s final ``extension,'' if any, | |
1505 after applying @code{file-name-sans-versions} to remove any | |
1506 version/backup part. It returns @code{nil} for extensionless file | |
1507 names such as @file{foo}. If @var{period} is non-@code{nil}, then the | |
1508 returned value includes the period that delimits the extension, and if | |
1509 @var{filename} has no extension, the value is @code{""}. If the last | |
1510 component of a file name begins with a @samp{.}, that @samp{.} doesn't | |
1511 count as the beginning of an extension, so, for example, | |
1512 @file{.emacs}'s ``extension'' is @code{nil}, not @samp{.emacs}. | |
1513 @end defun | |
1514 | |
1515 @defun file-name-sans-versions filename &optional keep-backup-version | 1571 @defun file-name-sans-versions filename &optional keep-backup-version |
1516 This function returns @var{filename} with any file version numbers, | 1572 This function returns @var{filename} with any file version numbers, |
1517 backup version numbers, or trailing tildes discarded. | 1573 backup version numbers, or trailing tildes discarded. |
1518 | 1574 |
1519 If @var{keep-backup-version} is non-@code{nil}, then true file version | 1575 If @var{keep-backup-version} is non-@code{nil}, then true file version |
1539 @result{} "foo" | 1595 @result{} "foo" |
1540 @end group | 1596 @end group |
1541 @end example | 1597 @end example |
1542 @end defun | 1598 @end defun |
1543 | 1599 |
1600 @defun file-name-extension filename &optional period | |
1601 This function returns @var{filename}'s final ``extension'', if any, | |
1602 after applying @code{file-name-sans-versions} to remove any | |
1603 version/backup part. The extension, in a file name, is the part that | |
1604 starts with the last @samp{.} in the last name component (minus | |
1605 any version/backup part). | |
1606 | |
1607 This function returns @code{nil} for extensionless file names such as | |
1608 @file{foo}. It returns @code{""} for null extensions, as in | |
1609 @file{foo.}. If the last component of a file name begins with a | |
1610 @samp{.}, that @samp{.} doesn't count as the beginning of an | |
1611 extension. Thus, @file{.emacs}'s ``extension'' is @code{nil}, not | |
1612 @samp{.emacs}. | |
1613 | |
1614 If @var{period} is non-@code{nil}, then the returned value includes | |
1615 the period that delimits the extension, and if @var{filename} has no | |
1616 extension, the value is @code{""}. | |
1617 @end defun | |
1618 | |
1544 @defun file-name-sans-extension filename | 1619 @defun file-name-sans-extension filename |
1545 This function returns @var{filename} minus its ``extension,'' if any. | 1620 This function returns @var{filename} minus its extension, if any. The |
1546 The extension, in a file name, is the part that starts with the last | 1621 version/backup part, if present, is only removed if the file has an |
1547 @samp{.} in the last name component, except if that @samp{.} is the | 1622 extension. For example, |
1548 first character of the file name's last component. For example, | |
1549 | 1623 |
1550 @example | 1624 @example |
1551 (file-name-sans-extension "foo.lose.c") | 1625 (file-name-sans-extension "foo.lose.c") |
1552 @result{} "foo.lose" | 1626 @result{} "foo.lose" |
1553 (file-name-sans-extension "big.hack/foo") | 1627 (file-name-sans-extension "big.hack/foo") |
1554 @result{} "big.hack/foo" | 1628 @result{} "big.hack/foo" |
1555 (file-name-sans-extension "/my/home/.emacs") | 1629 (file-name-sans-extension "/my/home/.emacs") |
1556 @result{} "/my/home/.emacs" | 1630 @result{} "/my/home/.emacs" |
1557 (file-name-sans-extension "/my/home/.emacs.el") | 1631 (file-name-sans-extension "/my/home/.emacs.el") |
1558 @result{} "/my/home/.emacs" | 1632 @result{} "/my/home/.emacs" |
1559 @end example | 1633 (file-name-sans-extension "~/foo.el.~3~") |
1634 @result{} "~/foo" | |
1635 (file-name-sans-extension "~/foo.~3~") | |
1636 @result{} "~/foo.~3~" | |
1637 @end example | |
1638 | |
1639 Note that the @samp{.~3~} in the two last examples is the backup part, | |
1640 not an extension. | |
1560 @end defun | 1641 @end defun |
1561 | 1642 |
1562 @ignore | 1643 @ignore |
1563 Andrew Innes says that this | 1644 Andrew Innes says that this |
1564 | 1645 |
1621 A @dfn{directory name} is the name of a directory. A directory is | 1702 A @dfn{directory name} is the name of a directory. A directory is |
1622 actually a kind of file, so it has a file name, which is related to | 1703 actually a kind of file, so it has a file name, which is related to |
1623 the directory name but not identical to it. (This is not quite the | 1704 the directory name but not identical to it. (This is not quite the |
1624 same as the usual Unix terminology.) These two different names for | 1705 same as the usual Unix terminology.) These two different names for |
1625 the same entity are related by a syntactic transformation. On GNU and | 1706 the same entity are related by a syntactic transformation. On GNU and |
1626 Unix systems, this is simple: a directory name ends in a slash (or | 1707 Unix systems, this is simple: a directory name ends in a slash, |
1627 backslash), whereas the directory's name as a file lacks that slash. | 1708 whereas the directory's name as a file lacks that slash. On MSDOS and |
1628 On MSDOS and VMS, the relationship is more complicated. | 1709 VMS, the relationship is more complicated. |
1629 | 1710 |
1630 The difference between a directory name and its name as a file is | 1711 The difference between a directory name and its name as a file is |
1631 subtle but crucial. When an Emacs variable or function argument is | 1712 subtle but crucial. When an Emacs variable or function argument is |
1632 described as being a directory name, a file name of a directory is not | 1713 described as being a directory name, a file name of a directory is not |
1633 acceptable. When @code{file-name-directory} returns a string, that is | 1714 acceptable. When @code{file-name-directory} returns a string, that is |
1634 always a directory name. | 1715 always a directory name. |
1635 | 1716 |
1636 The following two functions convert between directory names and file | 1717 The following two functions convert between directory names and file |
1637 names. They do nothing special with environment variable substitutions | 1718 names. They do nothing special with environment variable substitutions |
1638 such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}. | 1719 such as @samp{$HOME}, and the constructs @samp{~}, @samp{.} and @samp{..}. |
1639 | 1720 |
1640 @defun file-name-as-directory filename | 1721 @defun file-name-as-directory filename |
1641 This function returns a string representing @var{filename} in a form | 1722 This function returns a string representing @var{filename} in a form |
1642 that the operating system will interpret as the name of a directory. On | 1723 that the operating system will interpret as the name of a directory. On |
1643 most systems, this means appending a slash to the string (if it does not | 1724 most systems, this means appending a slash to the string (if it does not |
1711 The variable @code{directory-abbrev-alist} contains an alist of | 1792 The variable @code{directory-abbrev-alist} contains an alist of |
1712 abbreviations to use for file directories. Each element has the form | 1793 abbreviations to use for file directories. Each element has the form |
1713 @code{(@var{from} . @var{to})}, and says to replace @var{from} with | 1794 @code{(@var{from} . @var{to})}, and says to replace @var{from} with |
1714 @var{to} when it appears in a directory name. The @var{from} string is | 1795 @var{to} when it appears in a directory name. The @var{from} string is |
1715 actually a regular expression; it should always start with @samp{^}. | 1796 actually a regular expression; it should always start with @samp{^}. |
1716 The function @code{abbreviate-file-name} performs these substitutions. | 1797 The @var{to} string should be an ordinary absolute directory name. Do |
1798 not use @samp{~} to stand for a home directory in that string. The | |
1799 function @code{abbreviate-file-name} performs these substitutions. | |
1717 | 1800 |
1718 You can set this variable in @file{site-init.el} to describe the | 1801 You can set this variable in @file{site-init.el} to describe the |
1719 abbreviations appropriate for your site. | 1802 abbreviations appropriate for your site. |
1720 | 1803 |
1721 Here's an example, from a system on which file system @file{/home/fsf} | 1804 Here's an example, from a system on which file system @file{/home/fsf} |
1730 @end defvar | 1813 @end defvar |
1731 | 1814 |
1732 To convert a directory name to its abbreviation, use this | 1815 To convert a directory name to its abbreviation, use this |
1733 function: | 1816 function: |
1734 | 1817 |
1818 @anchor{Definition of abbreviate-file-name} | |
1735 @defun abbreviate-file-name filename | 1819 @defun abbreviate-file-name filename |
1736 This function applies abbreviations from @code{directory-abbrev-alist} | 1820 This function applies abbreviations from @code{directory-abbrev-alist} |
1737 to its argument, and substitutes @samp{~} for the user's home | 1821 to its argument, and substitutes @samp{~} for the user's home |
1738 directory. You can use it for directory names and for file names, | 1822 directory. You can use it for directory names and for file names, |
1739 because it recognizes abbreviations even as part of the name. | 1823 because it recognizes abbreviations even as part of the name. |
1746 @dfn{Expansion} of a file name means converting a relative file name | 1830 @dfn{Expansion} of a file name means converting a relative file name |
1747 to an absolute one. Since this is done relative to a default directory, | 1831 to an absolute one. Since this is done relative to a default directory, |
1748 you must specify the default directory name as well as the file name to | 1832 you must specify the default directory name as well as the file name to |
1749 be expanded. Expansion also simplifies file names by eliminating | 1833 be expanded. Expansion also simplifies file names by eliminating |
1750 redundancies such as @file{./} and @file{@var{name}/../}. | 1834 redundancies such as @file{./} and @file{@var{name}/../}. |
1835 | |
1836 In the next two functions, the @var{directory} argument can be either | |
1837 a directory name or a directory file name. @xref{Directory Names}. | |
1751 | 1838 |
1752 @defun expand-file-name filename &optional directory | 1839 @defun expand-file-name filename &optional directory |
1753 This function converts @var{filename} to an absolute file name. If | 1840 This function converts @var{filename} to an absolute file name. If |
1754 @var{directory} is supplied, it is the default directory to start with | 1841 @var{directory} is supplied, it is the default directory to start with |
1755 if @var{filename} is relative. (The value of @var{directory} should | 1842 if @var{filename} is relative. (The value of @var{directory} should |
1774 (expand-file-name "$HOME/foo") | 1861 (expand-file-name "$HOME/foo") |
1775 @result{} "/xcssun/users/rms/lewis/$HOME/foo" | 1862 @result{} "/xcssun/users/rms/lewis/$HOME/foo" |
1776 @end group | 1863 @end group |
1777 @end example | 1864 @end example |
1778 | 1865 |
1866 If the part of the combined file name before the first slash is | |
1867 @samp{~}, it expands to the value of the @env{HOME} environment | |
1868 variable (usually your home directory). If the part before the first | |
1869 slash is @samp{~@var{user}} and if @var{user} is a valid login name, | |
1870 it expands to @var{user}'s home directory. | |
1871 | |
1779 Filenames containing @samp{.} or @samp{..} are simplified to their | 1872 Filenames containing @samp{.} or @samp{..} are simplified to their |
1780 canonical form: | 1873 canonical form: |
1781 | 1874 |
1782 @example | 1875 @example |
1783 @group | 1876 @group |
1786 @end group | 1879 @end group |
1787 @end example | 1880 @end example |
1788 | 1881 |
1789 Note that @code{expand-file-name} does @emph{not} expand environment | 1882 Note that @code{expand-file-name} does @emph{not} expand environment |
1790 variables; only @code{substitute-in-file-name} does that. | 1883 variables; only @code{substitute-in-file-name} does that. |
1884 | |
1885 Note also that @code{expand-file-name} does not follow symbolic links | |
1886 at any level. This results in a difference between the way | |
1887 @code{file-truename} and @code{expand-file-name} treat @samp{..}. | |
1888 Assuming that @samp{/tmp/bar} is a symbolic link to the directory | |
1889 @samp{/tmp/foo/bar} we get: | |
1890 | |
1891 @example | |
1892 @group | |
1893 (file-truename "/tmp/bar/../myfile") | |
1894 @result{} "/tmp/foo/myfile" | |
1895 @end group | |
1896 @group | |
1897 (expand-file-name "/tmp/bar/../myfile") | |
1898 @result{} "/tmp/myfile" | |
1899 @end group | |
1900 @end example | |
1901 | |
1902 If you may need to follow symbolic links preceding @samp{..}, you | |
1903 should make sure to call @code{file-truename} without prior direct or | |
1904 indirect calls to @code{expand-file-name}. @xref{Truenames}. | |
1791 @end defun | 1905 @end defun |
1792 | 1906 |
1793 @c Emacs 19 feature | 1907 @c Emacs 19 feature |
1794 @defun file-relative-name filename &optional directory | 1908 @defun file-relative-name filename &optional directory |
1795 This function does the inverse of expansion---it tries to return a | 1909 This function does the inverse of expansion---it tries to return a |
1827 @result{} "/user/lewis/manual/" | 1941 @result{} "/user/lewis/manual/" |
1828 @end group | 1942 @end group |
1829 @end example | 1943 @end example |
1830 @end defvar | 1944 @end defvar |
1831 | 1945 |
1946 @anchor{Definition of substitute-in-file-name} | |
1832 @defun substitute-in-file-name filename | 1947 @defun substitute-in-file-name filename |
1833 This function replaces environment variables references in | 1948 This function replaces environment variable references in |
1834 @var{filename} with the environment variable values. Following | 1949 @var{filename} with the environment variable values. Following |
1835 standard Unix shell syntax, @samp{$} is the prefix to substitute an | 1950 standard Unix shell syntax, @samp{$} is the prefix to substitute an |
1836 environment variable value. If the input contains @samp{$$}, that is | 1951 environment variable value. If the input contains @samp{$$}, that is |
1837 converted to @samp{$}; this gives the user a way to ``quote'' a | 1952 converted to @samp{$}; this gives the user a way to ``quote'' a |
1838 @samp{$}. | 1953 @samp{$}. |
1860 (substitute-in-file-name "$HOME/foo") | 1975 (substitute-in-file-name "$HOME/foo") |
1861 @result{} "/xcssun/users/rms/foo" | 1976 @result{} "/xcssun/users/rms/foo" |
1862 @end group | 1977 @end group |
1863 @end example | 1978 @end example |
1864 | 1979 |
1865 After substitution, if a @samp{~} or a @samp{/} appears following a | 1980 After substitution, if a @samp{~} or a @samp{/} appears immediately |
1866 @samp{/}, everything before the following @samp{/} is discarded: | 1981 after another @samp{/}, the function discards everything before it (up |
1982 through the immediately preceding @samp{/}). | |
1867 | 1983 |
1868 @example | 1984 @example |
1869 @group | 1985 @group |
1870 (substitute-in-file-name "bar/~/foo") | 1986 (substitute-in-file-name "bar/~/foo") |
1871 @result{} "~/foo" | 1987 @result{} "~/foo" |
1893 | 2009 |
1894 @noindent | 2010 @noindent |
1895 The job of @code{make-temp-file} is to prevent two different users or | 2011 The job of @code{make-temp-file} is to prevent two different users or |
1896 two different jobs from trying to use the exact same file name. | 2012 two different jobs from trying to use the exact same file name. |
1897 | 2013 |
1898 @defun make-temp-file prefix &optional dir-flag | 2014 @defun make-temp-file prefix &optional dir-flag suffix |
1899 @tindex make-temp-file | 2015 @tindex make-temp-file |
1900 This function creates a temporary file and returns its name. | 2016 This function creates a temporary file and returns its name. |
1901 The name starts with @var{prefix}; it also contains a number that is | 2017 The name starts with @var{prefix}; it also contains a number that is |
1902 different in each Emacs job. If @var{prefix} is a relative file name, | 2018 different in each Emacs job. If @var{prefix} is a relative file name, |
1903 it is expanded against @code{temporary-file-directory}. | 2019 it is expanded against @code{temporary-file-directory}. |
1911 | 2027 |
1912 When @code{make-temp-file} returns, the file has been created and is | 2028 When @code{make-temp-file} returns, the file has been created and is |
1913 empty. At that point, you should write the intended contents into the | 2029 empty. At that point, you should write the intended contents into the |
1914 file. | 2030 file. |
1915 | 2031 |
1916 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates | 2032 If @var{dir-flag} is non-@code{nil}, @code{make-temp-file} creates an |
1917 an empty directory instead of an empty file. | 2033 empty directory instead of an empty file. It returns the file name, |
2034 not the directory name, of that directory. @xref{Directory Names}. | |
2035 | |
2036 If @var{suffix} is non-@code{nil}, @code{make-temp-file} adds it at | |
2037 the end of the file name. | |
1918 | 2038 |
1919 To prevent conflicts among different libraries running in the same | 2039 To prevent conflicts among different libraries running in the same |
1920 Emacs, each Lisp program that uses @code{make-temp-file} should have its | 2040 Emacs, each Lisp program that uses @code{make-temp-file} should have its |
1921 own @var{prefix}. The number added to the end of @var{prefix} | 2041 own @var{prefix}. The number added to the end of @var{prefix} |
1922 distinguishes between the same application running in different Emacs | 2042 distinguishes between the same application running in different Emacs |
1942 | 2062 |
1943 @defun make-temp-name string | 2063 @defun make-temp-name string |
1944 This function generates a string that can be used as a unique file name. | 2064 This function generates a string that can be used as a unique file name. |
1945 The name starts with @var{string}, and contains a number that is | 2065 The name starts with @var{string}, and contains a number that is |
1946 different in each Emacs job. It is like @code{make-temp-file} except | 2066 different in each Emacs job. It is like @code{make-temp-file} except |
1947 that it just constructs a name, and does not create a file. On MS-DOS, | 2067 that it just constructs a name, and does not create a file. Another |
1948 the @var{string} prefix can be truncated to fit into the 8+3 file-name | 2068 difference is that @var{string} should be an absolute file name. On |
1949 limits. | 2069 MS-DOS, this function can truncate the @var{string} prefix to fit into |
2070 the 8+3 file-name limits. | |
1950 @end defun | 2071 @end defun |
1951 | 2072 |
1952 @defvar temporary-file-directory | 2073 @defvar temporary-file-directory |
1953 @cindex @code{TMPDIR} environment variable | 2074 @cindex @code{TMPDIR} environment variable |
1954 @cindex @code{TMP} environment variable | 2075 @cindex @code{TMP} environment variable |
1962 The default value is determined in a reasonable way for your operating | 2083 The default value is determined in a reasonable way for your operating |
1963 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP} | 2084 system; it is based on the @code{TMPDIR}, @code{TMP} and @code{TEMP} |
1964 environment variables, with a fall-back to a system-dependent name if | 2085 environment variables, with a fall-back to a system-dependent name if |
1965 none of these variables is defined. | 2086 none of these variables is defined. |
1966 | 2087 |
1967 Even if you do not use @code{make-temp-name} to choose the temporary | 2088 Even if you do not use @code{make-temp-file} to create the temporary |
1968 file's name, you should still use this variable to decide which | 2089 file, you should still use this variable to decide which directory to |
1969 directory to put the file in. However, if you expect the file to be | 2090 put the file in. However, if you expect the file to be small, you |
1970 small, you should use @code{small-temporary-file-directory} first if | 2091 should use @code{small-temporary-file-directory} first if that is |
1971 that is non-@code{nil}. | 2092 non-@code{nil}. |
1972 @end defvar | 2093 @end defvar |
1973 | 2094 |
1974 @tindex small-temporary-file-directory | 2095 @tindex small-temporary-file-directory |
1975 @defvar small-temporary-file-directory | 2096 @defvar small-temporary-file-directory |
1976 This variable (new in Emacs 21) specifies the directory name for | 2097 This variable (new in Emacs 21) specifies the directory name for |
2064 @end defun | 2185 @end defun |
2065 | 2186 |
2066 @defopt completion-ignored-extensions | 2187 @defopt completion-ignored-extensions |
2067 @code{file-name-completion} usually ignores file names that end in any | 2188 @code{file-name-completion} usually ignores file names that end in any |
2068 string in this list. It does not ignore them when all the possible | 2189 string in this list. It does not ignore them when all the possible |
2069 completions end in one of these suffixes or when a buffer showing all | 2190 completions end in one of these suffixes. This variable has no effect |
2070 possible completions is displayed.@refill | 2191 on @code{file-name-all-completions}.@refill |
2071 | 2192 |
2072 A typical value might look like this: | 2193 A typical value might look like this: |
2073 | 2194 |
2074 @example | 2195 @example |
2075 @group | 2196 @group |
2174 | 2295 |
2175 An error is signaled if @var{directory} is not the name of a directory | 2296 An error is signaled if @var{directory} is not the name of a directory |
2176 that can be read. | 2297 that can be read. |
2177 @end defun | 2298 @end defun |
2178 | 2299 |
2179 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort | 2300 @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format |
2180 This is similar to @code{directory-files} in deciding which files | 2301 This is similar to @code{directory-files} in deciding which files |
2181 to report on and how to report their names. However, instead | 2302 to report on and how to report their names. However, instead |
2182 of returning a list of file names, it returns for each file a | 2303 of returning a list of file names, it returns for each file a |
2183 list @code{(@var{filename} . @var{attributes})}, where @var{attributes} | 2304 list @code{(@var{filename} . @var{attributes})}, where @var{attributes} |
2184 is what @code{file-attributes} would return for that file. | 2305 is what @code{file-attributes} would return for that file. |
2306 The optional argument @var{id-format} has the same meaning as the | |
2307 corresponding argument to @code{file-attributes} (@pxref{Definition | |
2308 of file-attributes}). | |
2185 @end defun | 2309 @end defun |
2186 | 2310 |
2187 @defun file-name-all-versions file dirname | 2311 @defun file-name-all-versions file dirname |
2188 This function returns a list of all versions of the file named | 2312 This function returns a list of all versions of the file named |
2189 @var{file} in directory @var{dirname}. | 2313 @var{file} in directory @var{dirname}. It is only available on VMS. |
2190 @end defun | 2314 @end defun |
2191 | 2315 |
2192 @tindex file-expand-wildcards | 2316 @tindex file-expand-wildcards |
2193 @defun file-expand-wildcards pattern &optional full | 2317 @defun file-expand-wildcards pattern &optional full |
2194 This function expands the wildcard pattern @var{pattern}, returning | 2318 This function expands the wildcard pattern @var{pattern}, returning |
2205 | 2329 |
2206 @defun insert-directory file switches &optional wildcard full-directory-p | 2330 @defun insert-directory file switches &optional wildcard full-directory-p |
2207 This function inserts (in the current buffer) a directory listing for | 2331 This function inserts (in the current buffer) a directory listing for |
2208 directory @var{file}, formatted with @code{ls} according to | 2332 directory @var{file}, formatted with @code{ls} according to |
2209 @var{switches}. It leaves point after the inserted text. | 2333 @var{switches}. It leaves point after the inserted text. |
2334 @var{switches} may be a string of options, or a list of strings | |
2335 representing individual options. | |
2210 | 2336 |
2211 The argument @var{file} may be either a directory name or a file | 2337 The argument @var{file} may be either a directory name or a file |
2212 specification including wildcard characters. If @var{wildcard} is | 2338 specification including wildcard characters. If @var{wildcard} is |
2213 non-@code{nil}, that means treat @var{file} as a file specification with | 2339 non-@code{nil}, that means treat @var{file} as a file specification with |
2214 wildcards. | 2340 wildcards. |
2226 @code{shell-file-name}, to expand the wildcards. | 2352 @code{shell-file-name}, to expand the wildcards. |
2227 | 2353 |
2228 MS-DOS and MS-Windows systems usually lack the standard Unix program | 2354 MS-DOS and MS-Windows systems usually lack the standard Unix program |
2229 @code{ls}, so this function emulates the standard Unix program @code{ls} | 2355 @code{ls}, so this function emulates the standard Unix program @code{ls} |
2230 with Lisp code. | 2356 with Lisp code. |
2357 | |
2358 As a technical detail, when @var{switches} contains the long | |
2359 @samp{--dired} option, @code{insert-directory} treats it specially, | |
2360 for the sake of dired. However, the normally equivalent short | |
2361 @samp{-D} option is just passed on to @code{insert-directory-program}, | |
2362 as any other option. | |
2231 @end defun | 2363 @end defun |
2232 | 2364 |
2233 @defvar insert-directory-program | 2365 @defvar insert-directory-program |
2234 This variable's value is the program to run to generate a directory listing | 2366 This variable's value is the program to run to generate a directory listing |
2235 for the function @code{insert-directory}. It is ignored on systems | 2367 for the function @code{insert-directory}. It is ignored on systems |
2245 with @code{delete-file}. These special functions exist to create and | 2377 with @code{delete-file}. These special functions exist to create and |
2246 delete directories. | 2378 delete directories. |
2247 | 2379 |
2248 @defun make-directory dirname &optional parents | 2380 @defun make-directory dirname &optional parents |
2249 This function creates a directory named @var{dirname}. | 2381 This function creates a directory named @var{dirname}. |
2250 If @var{parents} is non-@code{nil}, that means to create | 2382 If @var{parents} is non-@code{nil}, as is always the case in an |
2251 the parent directories first, if they don't already exist. | 2383 interactive call, that means to create the parent directories first, |
2384 if they don't already exist. | |
2252 @end defun | 2385 @end defun |
2253 | 2386 |
2254 @defun delete-directory dirname | 2387 @defun delete-directory dirname |
2255 This function deletes the directory named @var{dirname}. The function | 2388 This function deletes the directory named @var{dirname}. The function |
2256 @code{delete-file} does not work for files that are directories; you | 2389 @code{delete-file} does not work for files that are directories; you |
2257 must use @code{delete-directory} for them. If the directory contains | 2390 must use @code{delete-directory} for them. If the directory contains |
2258 any files, @code{delete-directory} signals an error. | 2391 any files, @code{delete-directory} signals an error. |
2392 | |
2393 This function only follows symbolic links at the level of parent | |
2394 directories. | |
2259 @end defun | 2395 @end defun |
2260 | 2396 |
2261 @node Magic File Names | 2397 @node Magic File Names |
2262 @section Making Certain File Names ``Magic'' | 2398 @section Making Certain File Names ``Magic'' |
2263 @cindex magic file names | 2399 @cindex magic file names |
2285 All the Emacs primitives for file access and file name transformation | 2421 All the Emacs primitives for file access and file name transformation |
2286 check the given file name against @code{file-name-handler-alist}. If | 2422 check the given file name against @code{file-name-handler-alist}. If |
2287 the file name matches @var{regexp}, the primitives handle that file by | 2423 the file name matches @var{regexp}, the primitives handle that file by |
2288 calling @var{handler}. | 2424 calling @var{handler}. |
2289 | 2425 |
2290 The first argument given to @var{handler} is the name of the primitive; | 2426 The first argument given to @var{handler} is the name of the |
2291 the remaining arguments are the arguments that were passed to that | 2427 primitive, as a symbol; the remaining arguments are the arguments that |
2292 primitive. (The first of these arguments is most often the file name | 2428 were passed to that primitive. (The first of these arguments is most |
2293 itself.) For example, if you do this: | 2429 often the file name itself.) For example, if you do this: |
2294 | 2430 |
2295 @example | 2431 @example |
2296 (file-exists-p @var{filename}) | 2432 (file-exists-p @var{filename}) |
2297 @end example | 2433 @end example |
2298 | 2434 |
2499 nothing and returns @code{nil}. Otherwise it returns the file name | 2635 nothing and returns @code{nil}. Otherwise it returns the file name |
2500 of the local copy file. | 2636 of the local copy file. |
2501 @end defun | 2637 @end defun |
2502 | 2638 |
2503 @defun file-remote-p filename | 2639 @defun file-remote-p filename |
2504 This functions return @code{t} if @var{filename} is a remote file---that is, | 2640 This function returns @code{t} if @var{filename} is a remote file---that is, |
2505 a magic file name that handles @code{file-local-copy}. | 2641 a magic file name that handles @code{file-local-copy}. |
2506 @end defun | 2642 @end defun |
2507 | 2643 |
2508 @defun unhandled-file-name-directory filename | 2644 @defun unhandled-file-name-directory filename |
2509 This function returns the name of a directory that is not magic. It | 2645 This function returns the name of a directory that is not magic. It |
2629 | 2765 |
2630 When @code{write-region} writes data into a file, it first calls the | 2766 When @code{write-region} writes data into a file, it first calls the |
2631 encoding functions for the formats listed in @code{buffer-file-format}, | 2767 encoding functions for the formats listed in @code{buffer-file-format}, |
2632 in the order of appearance in the list. | 2768 in the order of appearance in the list. |
2633 | 2769 |
2634 @deffn Command format-write-file file format | 2770 @deffn Command format-write-file file format &optional confirm |
2635 This command writes the current buffer contents into the file @var{file} | 2771 This command writes the current buffer contents into the file |
2636 in format @var{format}, and makes that format the default for future | 2772 @var{file} in format @var{format}, and makes that format the default |
2637 saves of the buffer. The argument @var{format} is a list of format | 2773 for future saves of the buffer. The argument @var{format} is a list |
2638 names. | 2774 of format names. Except for the @var{format} argument, this command |
2775 is similar to @code{write-file}. In particular, @var{confirm} has the | |
2776 same meaning and interactive treatment as the corresponding argument | |
2777 to @code{write-file}. @xref{Definition of write-file}. | |
2639 @end deffn | 2778 @end deffn |
2640 | 2779 |
2641 @deffn Command format-find-file file format | 2780 @deffn Command format-find-file file format |
2642 This command finds the file @var{file}, converting it according to | 2781 This command finds the file @var{file}, converting it according to |
2643 format @var{format}. It also makes @var{format} the default if the | 2782 format @var{format}. It also makes @var{format} the default if the |
2665 | 2804 |
2666 @defvar auto-save-file-format | 2805 @defvar auto-save-file-format |
2667 This variable specifies the format to use for auto-saving. Its value is | 2806 This variable specifies the format to use for auto-saving. Its value is |
2668 a list of format names, just like the value of | 2807 a list of format names, just like the value of |
2669 @code{buffer-file-format}; however, it is used instead of | 2808 @code{buffer-file-format}; however, it is used instead of |
2670 @code{buffer-file-format} for writing auto-save files. This variable is | 2809 @code{buffer-file-format} for writing auto-save files. If the value |
2671 always buffer-local in all buffers. | 2810 is @code{t}, the default, auto-saving uses the same format as a |
2811 regular save in the same buffer. This variable is always buffer-local | |
2812 in all buffers. | |
2672 @end defvar | 2813 @end defvar |
2673 | 2814 |
2674 @ignore | 2815 @ignore |
2675 arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c | 2816 arch-tag: 141f74ce-6ae3-40dc-a6c4-ef83fc4ec35c |
2676 @end ignore | 2817 @end ignore |