| blob | 9ac3ae31864463a86cdec479c3fcd3fc7b32282e |
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 0
528 ;; Note: in case the file is stat'able, POSIX
529 ;; realpath(3) gets us a canonical absolute
530 ;; filename, even if the post-merge PATHNAME
531 ;; is not absolute...
535 realpath
537 filename errno)))
540 ;; ... but without any trailing slash.
546 ;; SBCL has for many years had a policy that a pathname
547 ;; that names an existing, dangling or self-referential
548 ;; symlink denotes the symlink itself. stat(2) fails
549 ;; and sets errno to ELOOP in this case, but we must
550 ;; distinguish cases where the symlink exists from ones
551 ;; where there's a loop in the apparent containing
552 ;; directory.
553 #!-win32
555 size atime mtime)
560 linkp)
563 (:truename
564 ;; So here's a trick: since lstat succeded,
565 ;; FILENAME exists, so its directory exists and
566 ;; only the non-directory part is loopy. So
567 ;; let's resolve FILENAME's directory part with
568 ;; realpath(3), in order to get a canonical
569 ;; absolute name for the directory, and then
570 ;; return a pathname having PATHNAME's name,
571 ;; type, and version, but the rest from the
572 ;; truename of the directory. Since we turned
573 ;; PATHNAME into FILENAME "as a file", FILENAME
574 ;; does not end in a slash, and so we get the
575 ;; directory part of FILENAME by reparsing
576 ;; FILENAME and masking off its name, type, and
577 ;; version bits. But note not to call ourselves
578 ;; recursively, because we don't want to
579 ;; re-merge against *DEFAULT-PATHNAME-DEFAULTS*,
580 ;; since PATHNAME may be a relative pathname.
583 0
593 filename
597 realpath
599 filename errno)))
603 pathname))
606 ;; If we're still here, the file doesn't exist; return
607 ;; NIL or error.
609 nil
612 pathspec errno))))))))
616 #!+sb-doc
617 "Return the truename of PATHSPEC if such a file exists, the
618 coercion of PATHSPEC to a pathname if PATHSPEC names a symlink
619 that links to itself or to a file that doesn't exist, or NIL if
620 errno is set to ENOENT after trying to stat(2) the file. An
621 error of type FILE-ERROR is signaled if PATHSPEC is a wild
622 pathname, or for any other circumstance where stat(2) fails."
627 #!+sb-doc
628 "If PATHSPEC is a pathname that names an existing file, return
629 a pathname that denotes a canonicalized name for the file. If
630 pathspec is a stream associated with a file, return a pathname
631 that denotes a canonicalized name for the file associated with
632 the stream.
634 An error of type FILE-ERROR is signalled if no such file exists
635 or if the file system is such that a canonicalized file name
636 cannot be determined or if the pathname is wild.
638 Under Unix, the TRUENAME of a symlink that links to itself or to
639 a file that doesn't exist is considered to be the name of the
640 broken symlink itself."
641 ;; Note that eventually this routine might be different for streams
642 ;; than for other pathname designators.
648 #!+sb-doc
649 "Return the author of the file specified by PATHSPEC. Signal an
650 error of type FILE-ERROR if no such file exists, or if PATHSPEC
651 is a wild pathname."
655 #!+sb-doc
656 "Return the write date of the file specified by PATHSPEC.
657 An error of type FILE-ERROR is signaled if no such file exists,
658 or if PATHSPEC is a wild pathname."
660 \f
661 ;;;; miscellaneous other operations
666 #!+sb-doc
667 "Rename FILE to have the specified NEW-NAME. If FILE is a stream open to a
668 file, then the associated file is renamed."
675 :pathname new-name
682 :pathname new-name
684 ~I~_~A~:>"
691 #!+sb-doc
692 "Delete the specified FILE."
698 :pathname file
704 t)
705 \f
708 ;; SBCL_HOME isn't set for :EXECUTABLE T embedded cores
716 ;;; (This is an ANSI Common Lisp function.)
718 #!+sb-doc
719 "Return the home directory of the user as a pathname. If the HOME
720 environment variable has been specified, the directory it designates
721 is returned; otherwise obtains the home directory from the operating
722 system."
727 env-home
728 #!-win32
730 #!+win32
731 ;; Needs to bypass PARSE-NATIVE-NAMESTRING & ENSURE-TRAILING-SLASH
732 ;; What?! -- RMK, 2007-12-31
739 \f
740 ;;;; DIRECTORY
744 ;;; NOTE: There is a fair amount of hair below that is probably not
745 ;;; strictly necessary.
746 ;;;
747 ;;; The issue is the following: what does (DIRECTORY "SYS:*;") mean?
748 ;;; Until 2004-01, SBCL's behaviour was unquestionably wrong, as it
749 ;;; did not translate the logical pathname at all, but instead treated
750 ;;; it as a physical one. Other Lisps seem to to treat this call as
751 ;;; equivalent to (DIRECTORY (TRANSLATE-LOGICAL-PATHNAME "SYS:*;")),
752 ;;; which is fine as far as it goes, but not very interesting, and
753 ;;; arguably counterintuitive. (PATHNAME-MATCH-P "SYS:SRC;" "SYS:*;")
754 ;;; is true, so why should "SYS:SRC;" not show up in the call to
755 ;;; DIRECTORY? (assuming the physical pathname corresponding to it
756 ;;; exists, of course).
757 ;;;
758 ;;; So, the interpretation that I am pushing is for all pathnames
759 ;;; matching the input pathname to be queried. This means that we
760 ;;; need to compute the intersection of the input pathname and the
761 ;;; logical host FROM translations, and then translate the resulting
762 ;;; pathname using the host to the TO translation; this treatment is
763 ;;; recursively invoked until we get a physical pathname, whereupon
764 ;;; our physical DIRECTORY implementation takes over.
766 ;;; FIXME: this is an incomplete implementation. It only works when
767 ;;; both are logical pathnames (which is OK, because that's the only
768 ;;; case when we call it), but there are other pitfalls as well: see
769 ;;; the DIRECTORY-HELPER below for some, but others include a lack of
770 ;;; pattern handling.
772 ;;; The above was written by CSR, I (RMK) believe. The argument that
773 ;;; motivates the interpretation is faulty, however: PATHNAME-MATCH-P
774 ;;; returns true for (PATHNAME-MATCH-P #P"/tmp/*/" #P"/tmp/../"), but
775 ;;; the latter pathname is not in the result of DIRECTORY on the
776 ;;; former. Indeed, if DIRECTORY were constrained to return the
777 ;;; truename for every pathname for which PATHNAME-MATCH-P returned
778 ;;; true and which denoted a filename that named an existing file,
779 ;;; (DIRECTORY #P"/tmp/**/") would be required to list every file on a
780 ;;; Unix system, since any file can be named as though it were "below"
781 ;;; /tmp, given the dotdot entries. So I think the strongest
782 ;;; "consistency" we can define between PATHNAME-MATCH-P and DIRECTORY
783 ;;; is that PATHNAME-MATCH-P returns true of everything DIRECTORY
784 ;;; returns, but not vice versa.
786 ;;; In any case, even if the motivation were sound, DIRECTORY on a
787 ;;; wild logical pathname has no portable semantics. I see nothing in
788 ;;; ANSI that requires implementations to support wild physical
789 ;;; pathnames, and so there need not be any translation of a wild
790 ;;; logical pathname to a phyiscal pathname. So a program that calls
791 ;;; DIRECTORY on a wild logical pathname is doing something
792 ;;; non-portable at best. And if the only sensible semantics for
793 ;;; DIRECTORY on a wild logical pathname is something like the
794 ;;; following, it would be just as well if it signaled an error, since
795 ;;; a program can't possibly rely on the result of an intersection of
796 ;;; user-defined translations with a file system probe. (Potentially
797 ;;; useful kinds of "pathname" that might not support wildcards could
798 ;;; include pathname hosts that model unqueryable namespaces like HTTP
799 ;;; URIs, or that model namespaces that it's not convenient to
800 ;;; investigate, such as the namespace of TCP ports that some network
801 ;;; host listens on. I happen to think it a bad idea to try to
802 ;;; shoehorn such namespaces into a pathnames system, but people
803 ;;; sometimes claim to want pathnames for these things.) -- RMK
804 ;;; 2007-12-31.
812 integer)))
814 integer)))
857 ;;; FIXME: written as its own function because I (CSR) don't
858 ;;; understand it, so helping both debuggability and modularity. In
859 ;;; case anyone is motivated to rewrite it, it returns a list of
860 ;;; sublists representing the intersection of the two input directory
861 ;;; paths (excluding the initial :ABSOLUTE or :RELATIVE).
862 ;;;
863 ;;; FIXME: Does not work with :UP or :BACK
864 ;;; FIXME: Does not work with patterns
865 ;;;
866 ;;; FIXME: PFD suggests replacing this implementation with a DFA
867 ;;; conversion of a NDFA. Find out (a) what this means and (b) if it
868 ;;; turns out to be worth it.
922 #!+sb-doc
923 "Return a list of PATHNAMEs, each the TRUENAME of a file that matched the
924 given pathname. Note that the interaction between this ANSI-specified
925 TRUENAMEing and the semantics of the Unix filesystem (symbolic links..)
926 means this function can sometimes return files which don't have the same
927 directory as PATHNAME."
929 ;; as an asymptotically efficient way of removing duplicates
930 ;; (which can arise when e.g. multiple symlinks map to the
931 ;; same truename).
933 ;; FIXME: Possibly this MERGE-PATHNAMES call should only
934 ;; happen once we get a physical pathname.
940 ;; FIXME: Why not TRUENAME? As reported by
941 ;; Milan Zamazal sbcl-devel 2003-10-05, using
942 ;; TRUENAME causes a race condition whereby
943 ;; removal of a file during the directory
944 ;; operation causes an error. It's not clear
945 ;; what the right thing to do is, though. --
946 ;; CSR, 2003-10-13
950 truename)))))
963 ;; Sorting isn't required by the ANSI spec, but sorting
964 ;; into some canonical order seems good just on the
965 ;; grounds that the implementation should have repeatable
966 ;; behavior when possible.
972 \f
975 ;;; predicate to order pathnames by; goes by name
976 ;; FIXME: Does anything use this? It's not exported, and I don't find
977 ;; the name anywhere else.
987 xn)))
988 \f
990 #!+sb-doc
991 "Test whether the directories containing the specified file
992 actually exist, and attempt to create them if they do not.
993 The MODE argument is a CMUCL/SBCL-specific extension to control
994 the Unix permission bits."
1012 "~&creating directory: ~A~%"
1013 namestring))
1017 'simple-file-error
1018 :pathname pathspec
1019 :format-control
1020 "can't create directory ~A"
1025 pathspec
1028 :report
1029 "Continue as if directory creation was successful."
1030 nil)))