| blob | 04e6503e4bb75717157c9777d376de654a79f4bf |
1 ;;;; file system interface functions -- fairly Unix-centric, but with
2 ;;;; differences between Unix and Win32 papered over.
4 ;;;; This software is part of the SBCL system. See the README file for
5 ;;;; more information.
6 ;;;;
7 ;;;; This software is derived from the CMU CL system, which was
8 ;;;; written at Carnegie Mellon University and released into the
9 ;;;; public domain. The software is in the public domain and is
10 ;;;; provided with absolutely no warranty. See the COPYING and CREDITS
11 ;;;; files for more information.
14 \f
15 ;;;; Unix pathname host support
17 ;;; FIXME: the below shouldn't really be here, but in documentation
18 ;;; (chapter 19 makes a lot of requirements for documenting
19 ;;; implementation-dependent decisions), but anyway it's probably not
20 ;;; what we currently do.
21 ;;;
22 ;;; Unix namestrings have the following format:
23 ;;;
24 ;;; namestring := [ directory ] [ file [ type [ version ]]]
25 ;;; directory := [ "/" ] { file "/" }*
26 ;;; file := [^/]*
27 ;;; type := "." [^/.]*
28 ;;; version := "." ([0-9]+ | "*")
29 ;;;
30 ;;; Note: this grammar is ambiguous. The string foo.bar.5 can be
31 ;;; parsed as either just the file specified or as specifying the
32 ;;; file, type, and version. Therefore, we use the following rules
33 ;;; when confronted with an ambiguous file.type.version string:
34 ;;;
35 ;;; - If the first character is a dot, it's part of the file. It is not
36 ;;; considered a dot in the following rules.
37 ;;;
38 ;;; - Otherwise, the last dot separates the file and the type.
39 ;;;
40 ;;; Wildcard characters:
41 ;;;
42 ;;; If the directory, file, type components contain any of the
43 ;;; following characters, it is considered part of a wildcard pattern
44 ;;; and has the following meaning.
45 ;;;
46 ;;; ? - matches any one character
47 ;;; * - matches any zero or more characters.
48 ;;; [abc] - matches any of a, b, or c.
49 ;;; {str1,str2,...,strn} - matches any of str1, str2, ..., or strn.
50 ;;; (FIXME: no it doesn't)
51 ;;;
52 ;;; Any of these special characters can be preceded by a backslash to
53 ;;; cause it to be treated as a regular character.
55 #!+sb-doc
57 checked for whatever they may have protected."
79 :namestring namestr
101 last-regular-char
102 index)
134 :namestring namestr
139 close-bracket)))
172 nil
177 \f
178 ;;;; wildcard matching stuff
180 ;;; Return a list of all the Lispy filenames (not including e.g. the
181 ;;; Unix magic "." and "..") in the directory named by DIRECTORY-NAME.
185 "alloc_directory_lispy_filenames"
187 directory-name)))
190 :pathname directory-name
197 adlf)))))
207 ,verify-existence
208 ,follow-links
214 ;;; Call FUNCTION on matches.
215 ;;;
216 ;;; KLUDGE: this assumes that an absolute pathname is indicated to the
217 ;;; operating system by having a directory separator as the first
218 ;;; character in the directory part. This is true for Win32 pathnames
219 ;;; and for Unix pathnames, but it isn't true for LispM pathnames (and
220 ;;; their bastard offspring, logical pathnames. Also it assumes that
221 ;;; Unix pathnames have an empty or :unspecific device, and that
222 ;;; windows drive letters are the only kinds of non-empty/:UNSPECIFIC
223 ;;; devices.
247 verify-existence follow-links nil function)
250 ;;; Call FUNCTION on directories.
252 follow-links nodes function
255 #!+win32
281 (%enumerate-directories
285 verify-existence follow-links
286 nodes function))))
288 ;; now with extra error case handling from CLHS
289 ;; 19.2.2.4.3 -- CSR, 2004-01-24
292 :pathname pathname
296 verify-existence follow-links
297 nodes function)
313 (%enumerate-directories subdir tail pathname
314 verify-existence follow-links
315 nodes function))))))))
329 verify-existence follow-links
330 nodes function))))))))
334 :pathname pathname
341 verify-existence follow-links
342 nodes function)))))
344 ;; :WILD-INFERIORS is handled above, so the only case here
345 ;; should be (:ABSOLUTE :BACK)
348 :pathname pathname
352 ;;; Call FUNCTION on files.
371 ;; I IGNORE-ERRORS here just because the original CMU CL
372 ;; code did. I think the intent is that it's not an error
373 ;; to request matches to a wild pattern when no matches
374 ;; exist, but I haven't tried to figure out whether
375 ;; everything is kosher. (E.g. what if we try to match a
376 ;; wildcard but we don't have permission to read one of the
377 ;; relevant directories?) -- WHN 2001-04-17
390 directory
391 complete-filename))))))
411 ;;; FIXME: Why do we need this?
435 \f
436 ;;;; UNIX-NAMESTRING
442 ;; KLUDGE: I'm not sure this second check should really
443 ;; have to be here. But on sbcl-0.6.12.7,
444 ;; (PATHNAME-DIRECTORY (PATHNAME "")) is NIL, and
445 ;; (PATHNAME "") seems to act like an empty relative
446 ;; pathname, so in order to work with that, I test
447 ;; for NIL here. -- WHN 2001-05-18
451 ;; (The ANSI definition of "pathname specifier" has
452 ;; other cases, but none of them seem to admit the possibility
453 ;; of being empty and relative.)
454 ))
456 ;;; Convert PATHNAME into a string that can be used with UNIX system
457 ;;; calls, or return NIL if no match is found. Wild-cards are expanded.
458 ;;;
459 ;;; FIXME: apart from the error checking (for wildness and for
460 ;;; existence) and conversion to physical pathanme, this is redundant
461 ;;; with UNPARSE-NATIVE-UNIX-NAMESTRING; one should probably be
462 ;;; written in terms of the other.
463 ;;;
464 ;;; FIXME: actually this (I think) works not just for Unix.
470 :pathname namestring
478 \f
479 ;;;; TRUENAME, PROBE-FILE, FILE-AUTHOR, FILE-WRITE-DATE.
481 ;;; Rewritten in 12/2007 by RMK, replacing 13+ year old CMU code that
482 ;;; made a mess of things in order to support search lists (which SBCL
483 ;;; has never had). These are now all relatively straightforward
484 ;;; wrappers around stat(2) and realpath(2), with the same basic logic
485 ;;; in all cases. The wrinkles to be aware of:
486 ;;;
487 ;;; * SBCL defines the truename of an existing, dangling or
488 ;;; self-referring symlink to be the symlink itself.
489 ;;; * The old version of PROBE-FILE merged the pathspec against
490 ;;; *DEFAULT-PATHNAME-DEFAULTS* twice, and so lost when *D-P-D*
491 ;;; was a relative pathname. Even if the case where *D-P-D* is a
492 ;;; relative pathname is problematic, there's no particular reason
493 ;;; to get that wrong, so let's try not to.
494 ;;; * Note that while stat(2) is probably atomic, getting the truename
495 ;;; for a filename involves poking all over the place, and so is
496 ;;; subject to race conditions if other programs mutate the file
497 ;;; system while we're resolving symlinks. So it's not implausible for
498 ;;; realpath(3) to fail even if stat(2) succeeded. There's nothing
499 ;;; obvious we can do about this, however.
500 ;;; * Windows' apparent analogue of realpath(3) is called
501 ;;; GetFullPathName, and it's a bit less useful than realpath(3).
502 ;;; In particular, while realpath(3) errors in case the file doesn't
503 ;;; exist, GetFullPathName seems to return a filename in all cases.
504 ;;; As realpath(3) is not atomic anyway, we only ever call it when
505 ;;; we think a file exists, so just be careful when rewriting this
506 ;;; routine.
514 :pathname pathname
516 (physicalized from ~A).~:>"
520 atime mtime)
526 ;; Note: in case the file is stat'able, POSIX
527 ;; realpath(3) gets us a canonical absolute
528 ;; filename, even if the post-merge PATHNAME
529 ;; is not absolute...
533 realpath
535 filename errno)))
538 ;; ... but without any trailing slash.
544 ;; SBCL has for many years had a policy that a pathname
545 ;; that names an existing, dangling or self-referential
546 ;; symlink denotes the symlink itself. stat(2) fails
547 ;; and sets errno to ELOOP in this case, but we must
548 ;; distinguish cases where the symlink exists from ones
549 ;; where there's a loop in the apparent containing
550 ;; directory.
551 #!-win32
553 size atime mtime)
558 linkp)
561 (:truename
562 ;; So here's a trick: since lstat succeded,
563 ;; FILENAME exists, so its directory exists and
564 ;; only the non-directory part is loopy. So
565 ;; let's resolve FILENAME's directory part with
566 ;; realpath(3), in order to get a canonical
567 ;; absolute name for the directory, and then
568 ;; return a pathname having PATHNAME's name,
569 ;; type, and version, but the rest from the
570 ;; truename of the directory. Since we turned
571 ;; PATHNAME into FILENAME "as a file", FILENAME
572 ;; does not end in a slash, and so we get the
573 ;; directory part of FILENAME by reparsing
574 ;; FILENAME and masking off its name, type, and
575 ;; version bits. But note not to call ourselves
576 ;; recursively, because we don't want to
577 ;; re-merge against *DEFAULT-PATHNAME-DEFAULTS*,
578 ;; since PATHNAME may be a relative pathname.
589 filename
593 realpath
595 filename errno)))
599 pathname))
602 ;; If we're still here, the file doesn't exist; return
603 ;; NIL or error.
605 nil
608 pathspec errno))))))))
612 #!+sb-doc
613 "Return the truename of PATHSPEC if such a file exists, the
614 coercion of PATHSPEC to a pathname if PATHSPEC names a symlink
615 that links to itself or to a file that doesn't exist, or NIL if
616 errno is set to ENOENT after trying to stat(2) the file. An
617 error of type FILE-ERROR is signaled if PATHSPEC is a wild
618 pathname, or for any other circumstance where stat(2) fails."
623 #!+sb-doc
624 "If PATHSPEC is a pathname that names an existing file, return
625 a pathname that denotes a canonicalized name for the file. If
626 pathspec is a stream associated with a file, return a pathname
627 that denotes a canonicalized name for the file associated with
628 the stream.
630 An error of type FILE-ERROR is signalled if no such file exists
631 or if the file system is such that a canonicalized file name
632 cannot be determined or if the pathname is wild.
634 Under Unix, the TRUENAME of a symlink that links to itself or to
635 a file that doesn't exist is considered to be the name of the
636 broken symlink itself."
637 ;; Note that eventually this routine might be different for streams
638 ;; than for other pathname designators.
644 #!+sb-doc
645 "Return the author of the file specified by PATHSPEC. Signal an
646 error of type FILE-ERROR if no such file exists, or if PATHSPEC
647 is a wild pathname."
651 #!+sb-doc
652 "Return the write date of the file specified by PATHSPEC.
653 An error of type FILE-ERROR is signaled if no such file exists,
654 or if PATHSPEC is a wild pathname."
656 \f
657 ;;;; miscellaneous other operations
662 #!+sb-doc
663 "Rename FILE to have the specified NEW-NAME. If FILE is a stream open to a
664 file, then the associated file is renamed."
671 :pathname new-name
678 :pathname new-name
680 ~I~_~A~:>"
687 #!+sb-doc
688 "Delete the specified FILE."
694 :pathname file
700 t)
701 \f
705 #!+win32
707 string
712 ;; SBCL_HOME isn't set for :EXECUTABLE T embedded cores
717 ;;; (This is an ANSI Common Lisp function.)
719 #!+sb-doc
720 "Return the home directory of the user as a pathname. If the HOME
721 environment variable has been specified, the directory it designates
722 is returned; otherwise obtains the home directory from the operating
723 system."
729 env-home
730 #!-win32
732 #!+win32
733 ;; Needs to bypass PARSE-NATIVE-NAMESTRING & ENSURE-TRAILING-SLASH
736 \f
737 ;;;; DIRECTORY
741 ;;; NOTE: There is a fair amount of hair below that is probably not
742 ;;; strictly necessary.
743 ;;;
744 ;;; The issue is the following: what does (DIRECTORY "SYS:*;") mean?
745 ;;; Until 2004-01, SBCL's behaviour was unquestionably wrong, as it
746 ;;; did not translate the logical pathname at all, but instead treated
747 ;;; it as a physical one. Other Lisps seem to to treat this call as
748 ;;; equivalent to (DIRECTORY (TRANSLATE-LOGICAL-PATHNAME "SYS:*;")),
749 ;;; which is fine as far as it goes, but not very interesting, and
750 ;;; arguably counterintuitive. (PATHNAME-MATCH-P "SYS:SRC;" "SYS:*;")
751 ;;; is true, so why should "SYS:SRC;" not show up in the call to
752 ;;; DIRECTORY? (assuming the physical pathname corresponding to it
753 ;;; exists, of course).
754 ;;;
755 ;;; So, the interpretation that I am pushing is for all pathnames
756 ;;; matching the input pathname to be queried. This means that we
757 ;;; need to compute the intersection of the input pathname and the
758 ;;; logical host FROM translations, and then translate the resulting
759 ;;; pathname using the host to the TO translation; this treatment is
760 ;;; recursively invoked until we get a physical pathname, whereupon
761 ;;; our physical DIRECTORY implementation takes over.
763 ;;; FIXME: this is an incomplete implementation. It only works when
764 ;;; both are logical pathnames (which is OK, because that's the only
765 ;;; case when we call it), but there are other pitfalls as well: see
766 ;;; the DIRECTORY-HELPER below for some, but others include a lack of
767 ;;; pattern handling.
774 integer)))
776 integer)))
819 ;;; FIXME: written as its own function because I (CSR) don't
820 ;;; understand it, so helping both debuggability and modularity. In
821 ;;; case anyone is motivated to rewrite it, it returns a list of
822 ;;; sublists representing the intersection of the two input directory
823 ;;; paths (excluding the initial :ABSOLUTE or :RELATIVE).
824 ;;;
825 ;;; FIXME: Does not work with :UP or :BACK
826 ;;; FIXME: Does not work with patterns
827 ;;;
828 ;;; FIXME: PFD suggests replacing this implementation with a DFA
829 ;;; conversion of a NDFA. Find out (a) what this means and (b) if it
830 ;;; turns out to be worth it.
884 #!+sb-doc
885 "Return a list of PATHNAMEs, each the TRUENAME of a file that matched the
886 given pathname. Note that the interaction between this ANSI-specified
887 TRUENAMEing and the semantics of the Unix filesystem (symbolic links..)
888 means this function can sometimes return files which don't have the same
889 directory as PATHNAME."
891 ;; as an asymptotically efficient way of removing duplicates
892 ;; (which can arise when e.g. multiple symlinks map to the
893 ;; same truename).
895 ;; FIXME: Possibly this MERGE-PATHNAMES call should only
896 ;; happen once we get a physical pathname.
902 ;; FIXME: Why not TRUENAME? As reported by
903 ;; Milan Zamazal sbcl-devel 2003-10-05, using
904 ;; TRUENAME causes a race condition whereby
905 ;; removal of a file during the directory
906 ;; operation causes an error. It's not clear
907 ;; what the right thing to do is, though. --
908 ;; CSR, 2003-10-13
912 truename)))))
925 ;; Sorting isn't required by the ANSI spec, but sorting
926 ;; into some canonical order seems good just on the
927 ;; grounds that the implementation should have repeatable
928 ;; behavior when possible.
934 \f
937 ;;; predicate to order pathnames by; goes by name
947 xn)))
948 \f
950 #!+sb-doc
951 "Test whether the directories containing the specified file
952 actually exist, and attempt to create them if they do not.
953 The MODE argument is a CMUCL/SBCL-specific extension to control
954 the Unix permission bits."
971 "~&creating directory: ~A~%"
972 namestring))
976 :pathname pathspec
984 nil)))