| blob | fb62f42036e9a672c73ce4af974ed9b8b7eba798 |
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
704 ;; SBCL_HOME isn't set for :EXECUTABLE T embedded cores
712 ;;; (This is an ANSI Common Lisp function.)
714 #!+sb-doc
715 "Return the home directory of the user as a pathname. If the HOME
716 environment variable has been specified, the directory it designates
717 is returned; otherwise obtains the home directory from the operating
718 system."
723 env-home
724 #!-win32
726 #!+win32
727 ;; Needs to bypass PARSE-NATIVE-NAMESTRING & ENSURE-TRAILING-SLASH
728 ;; What?! -- RMK, 2007-12-31
735 \f
736 ;;;; DIRECTORY
740 ;;; NOTE: There is a fair amount of hair below that is probably not
741 ;;; strictly necessary.
742 ;;;
743 ;;; The issue is the following: what does (DIRECTORY "SYS:*;") mean?
744 ;;; Until 2004-01, SBCL's behaviour was unquestionably wrong, as it
745 ;;; did not translate the logical pathname at all, but instead treated
746 ;;; it as a physical one. Other Lisps seem to to treat this call as
747 ;;; equivalent to (DIRECTORY (TRANSLATE-LOGICAL-PATHNAME "SYS:*;")),
748 ;;; which is fine as far as it goes, but not very interesting, and
749 ;;; arguably counterintuitive. (PATHNAME-MATCH-P "SYS:SRC;" "SYS:*;")
750 ;;; is true, so why should "SYS:SRC;" not show up in the call to
751 ;;; DIRECTORY? (assuming the physical pathname corresponding to it
752 ;;; exists, of course).
753 ;;;
754 ;;; So, the interpretation that I am pushing is for all pathnames
755 ;;; matching the input pathname to be queried. This means that we
756 ;;; need to compute the intersection of the input pathname and the
757 ;;; logical host FROM translations, and then translate the resulting
758 ;;; pathname using the host to the TO translation; this treatment is
759 ;;; recursively invoked until we get a physical pathname, whereupon
760 ;;; our physical DIRECTORY implementation takes over.
762 ;;; FIXME: this is an incomplete implementation. It only works when
763 ;;; both are logical pathnames (which is OK, because that's the only
764 ;;; case when we call it), but there are other pitfalls as well: see
765 ;;; the DIRECTORY-HELPER below for some, but others include a lack of
766 ;;; pattern handling.
768 ;;; The above was written by CSR, I (RMK) believe. The argument that
769 ;;; motivates the interpretation is faulty, however: PATHNAME-MATCH-P
770 ;;; returns true for (PATHNAME-MATCH-P #P"/tmp/*/" #P"/tmp/../"), but
771 ;;; the latter pathname is not in the result of DIRECTORY on the
772 ;;; former. Indeed, if DIRECTORY were constrained to return the
773 ;;; truename for every pathname for which PATHNAME-MATCH-P returned
774 ;;; true and which denoted a filename that named an existing file,
775 ;;; (DIRECTORY #P"/tmp/**/") would be required to list every file on a
776 ;;; Unix system, since any file can be named as though it were "below"
777 ;;; /tmp, given the dotdot entries. So I think the strongest
778 ;;; "consistency" we can define between PATHNAME-MATCH-P and DIRECTORY
779 ;;; is that PATHNAME-MATCH-P returns true of everything DIRECTORY
780 ;;; returns, but not vice versa.
782 ;;; In any case, even if the motivation were sound, DIRECTORY on a
783 ;;; wild logical pathname has no portable semantics. I see nothing in
784 ;;; ANSI that requires implementations to support wild physical
785 ;;; pathnames, and so there need not be any translation of a wild
786 ;;; logical pathname to a phyiscal pathname. So a program that calls
787 ;;; DIRECTORY on a wild logical pathname is doing something
788 ;;; non-portable at best. And if the only sensible semantics for
789 ;;; DIRECTORY on a wild logical pathname is something like the
790 ;;; following, it would be just as well if it signaled an error, since
791 ;;; a program can't possibly rely on the result of an intersection of
792 ;;; user-defined translations with a file system probe. (Potentially
793 ;;; useful kinds of "pathname" that might not support wildcards could
794 ;;; include pathname hosts that model unqueryable namespaces like HTTP
795 ;;; URIs, or that model namespaces that it's not convenient to
796 ;;; investigate, such as the namespace of TCP ports that some network
797 ;;; host listens on. I happen to think it a bad idea to try to
798 ;;; shoehorn such namespaces into a pathnames system, but people
799 ;;; sometimes claim to want pathnames for these things.) -- RMK
800 ;;; 2007-12-31.
808 integer)))
810 integer)))
853 ;;; FIXME: written as its own function because I (CSR) don't
854 ;;; understand it, so helping both debuggability and modularity. In
855 ;;; case anyone is motivated to rewrite it, it returns a list of
856 ;;; sublists representing the intersection of the two input directory
857 ;;; paths (excluding the initial :ABSOLUTE or :RELATIVE).
858 ;;;
859 ;;; FIXME: Does not work with :UP or :BACK
860 ;;; FIXME: Does not work with patterns
861 ;;;
862 ;;; FIXME: PFD suggests replacing this implementation with a DFA
863 ;;; conversion of a NDFA. Find out (a) what this means and (b) if it
864 ;;; turns out to be worth it.
918 #!+sb-doc
919 "Return a list of PATHNAMEs, each the TRUENAME of a file that matched the
920 given pathname. Note that the interaction between this ANSI-specified
921 TRUENAMEing and the semantics of the Unix filesystem (symbolic links..)
922 means this function can sometimes return files which don't have the same
923 directory as PATHNAME."
925 ;; as an asymptotically efficient way of removing duplicates
926 ;; (which can arise when e.g. multiple symlinks map to the
927 ;; same truename).
929 ;; FIXME: Possibly this MERGE-PATHNAMES call should only
930 ;; happen once we get a physical pathname.
936 ;; FIXME: Why not TRUENAME? As reported by
937 ;; Milan Zamazal sbcl-devel 2003-10-05, using
938 ;; TRUENAME causes a race condition whereby
939 ;; removal of a file during the directory
940 ;; operation causes an error. It's not clear
941 ;; what the right thing to do is, though. --
942 ;; CSR, 2003-10-13
946 truename)))))
959 ;; Sorting isn't required by the ANSI spec, but sorting
960 ;; into some canonical order seems good just on the
961 ;; grounds that the implementation should have repeatable
962 ;; behavior when possible.
968 \f
971 ;;; predicate to order pathnames by; goes by name
972 ;; FIXME: Does anything use this? It's not exported, and I don't find
973 ;; the name anywhere else.
983 xn)))
984 \f
986 #!+sb-doc
987 "Test whether the directories containing the specified file
988 actually exist, and attempt to create them if they do not.
989 The MODE argument is a CMUCL/SBCL-specific extension to control
990 the Unix permission bits."
1008 "~&creating directory: ~A~%"
1009 namestring))
1013 'simple-file-error
1014 :pathname pathspec
1015 :format-control
1016 "can't create directory ~A"
1021 pathspec
1024 :report
1025 "Continue as if directory creation was successful."
1026 nil)))