| blob | 4c2c05355337c2afeec49b383242ce31d7ae2c33 |
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)))))
201 ;; TODO: the implementation !enumerate-matches is some hairy stuff
202 ;; that we mostly don't need. Couldn't we use POSIX fts(3) to walk
203 ;; the file system and PATHNAME-MATCH-P to select matches, at least on
204 ;; Unices?
211 ,verify-existence
212 ,follow-links
218 ;;; Call FUNCTION on matches.
219 ;;;
220 ;;; KLUDGE: this assumes that an absolute pathname is indicated to the
221 ;;; operating system by having a directory separator as the first
222 ;;; character in the directory part. This is true for Win32 pathnames
223 ;;; and for Unix pathnames, but it isn't true for LispM pathnames (and
224 ;;; their bastard offspring, logical pathnames. Also it assumes that
225 ;;; Unix pathnames have an empty or :unspecific device, and that
226 ;;; windows drive letters are the only kinds of non-empty/:UNSPECIFIC
227 ;;; devices.
251 verify-existence follow-links nil function)
254 ;;; Call FUNCTION on directories.
256 follow-links nodes function
259 #!+win32
285 (%enumerate-directories
289 verify-existence follow-links
290 nodes function))))
292 ;; now with extra error case handling from CLHS
293 ;; 19.2.2.4.3 -- CSR, 2004-01-24
296 :pathname pathname
300 verify-existence follow-links
301 nodes function)
317 (%enumerate-directories subdir tail pathname
318 verify-existence follow-links
319 nodes function))))))))
333 verify-existence follow-links
334 nodes function))))))))
338 :pathname pathname
345 verify-existence follow-links
346 nodes function)))))
348 ;; :WILD-INFERIORS is handled above, so the only case here
349 ;; should be (:ABSOLUTE :BACK)
352 :pathname pathname
356 ;;; Call FUNCTION on files.
375 ;; I IGNORE-ERRORS here just because the original CMU CL
376 ;; code did. I think the intent is that it's not an error
377 ;; to request matches to a wild pattern when no matches
378 ;; exist, but I haven't tried to figure out whether
379 ;; everything is kosher. (E.g. what if we try to match a
380 ;; wildcard but we don't have permission to read one of the
381 ;; relevant directories?) -- WHN 2001-04-17
394 directory
395 complete-filename))))))
415 ;;; FIXME: Why do we need this?
439 \f
440 ;;;; UNIX-NAMESTRING
446 ;; KLUDGE: I'm not sure this second check should really
447 ;; have to be here. But on sbcl-0.6.12.7,
448 ;; (PATHNAME-DIRECTORY (PATHNAME "")) is NIL, and
449 ;; (PATHNAME "") seems to act like an empty relative
450 ;; pathname, so in order to work with that, I test
451 ;; for NIL here. -- WHN 2001-05-18
455 ;; (The ANSI definition of "pathname specifier" has
456 ;; other cases, but none of them seem to admit the possibility
457 ;; of being empty and relative.)
458 ))
460 ;;; Convert PATHNAME into a string that can be used with UNIX system
461 ;;; calls, or return NIL if no match is found. Wild-cards are expanded.
462 ;;;
463 ;;; FIXME: apart from the error checking (for wildness and for
464 ;;; existence) and conversion to physical pathanme, this is redundant
465 ;;; with UNPARSE-NATIVE-UNIX-NAMESTRING; one should probably be
466 ;;; written in terms of the other.
467 ;;;
468 ;;; FIXME: actually this (I think) works not just for Unix.
474 :pathname namestring
482 \f
483 ;;;; TRUENAME, PROBE-FILE, FILE-AUTHOR, FILE-WRITE-DATE.
485 ;;; Rewritten in 12/2007 by RMK, replacing 13+ year old CMU code that
486 ;;; made a mess of things in order to support search lists (which SBCL
487 ;;; has never had). These are now all relatively straightforward
488 ;;; wrappers around stat(2) and realpath(2), with the same basic logic
489 ;;; in all cases. The wrinkles to be aware of:
490 ;;;
491 ;;; * SBCL defines the truename of an existing, dangling or
492 ;;; self-referring symlink to be the symlink itself.
493 ;;; * The old version of PROBE-FILE merged the pathspec against
494 ;;; *DEFAULT-PATHNAME-DEFAULTS* twice, and so lost when *D-P-D*
495 ;;; was a relative pathname. Even if the case where *D-P-D* is a
496 ;;; relative pathname is problematic, there's no particular reason
497 ;;; to get that wrong, so let's try not to.
498 ;;; * Note that while stat(2) is probably atomic, getting the truename
499 ;;; for a filename involves poking all over the place, and so is
500 ;;; subject to race conditions if other programs mutate the file
501 ;;; system while we're resolving symlinks. So it's not implausible for
502 ;;; realpath(3) to fail even if stat(2) succeeded. There's nothing
503 ;;; obvious we can do about this, however.
504 ;;; * Windows' apparent analogue of realpath(3) is called
505 ;;; GetFullPathName, and it's a bit less useful than realpath(3).
506 ;;; In particular, while realpath(3) errors in case the file doesn't
507 ;;; exist, GetFullPathName seems to return a filename in all cases.
508 ;;; As realpath(3) is not atomic anyway, we only ever call it when
509 ;;; we think a file exists, so just be careful when rewriting this
510 ;;; routine.
511 ;;;
512 ;;; Given a pathname designator, some quality to query for, return one
513 ;;; of a pathname, a universal time, or a string (a file-author), or
514 ;;; NIL. QUERY-FOR may be one of :TRUENAME, :EXISTENCE, :WRITE-DATE,
515 ;;; :AUTHOR. If ERRORP is false, return NIL in case the file system
516 ;;; returns an error code; otherwise, signal an error. Accepts
517 ;;; logical pathnames, too (but never returns LPNs). For internal
518 ;;; use.
526 :pathname pathname
528 (physicalized from ~A).~:>"
536 atime mtime)
542 0
544 filename
550 0
552 ;; Note: in case the file is stat'able, POSIX
553 ;; realpath(3) gets us a canonical absolute
554 ;; filename, even if the post-merge PATHNAME
555 ;; is not absolute...
559 realpath
563 ;; ... but without any trailing slash.
569 ;; SBCL has for many years had a policy that a pathname
570 ;; that names an existing, dangling or self-referential
571 ;; symlink denotes the symlink itself. stat(2) fails
572 ;; and sets errno to ENOENT or ELOOP respectively, but
573 ;; we must distinguish cases where the symlink exists
574 ;; from ones where there's a loop in the apparent
575 ;; containing directory.
576 #!-win32
578 size atime mtime)
583 linkp)
586 (:existence
587 ;; We do this reparse so as to return a
588 ;; normalized pathname.
591 (:truename
592 ;; So here's a trick: since lstat succeded,
593 ;; FILENAME exists, so its directory exists and
594 ;; only the non-directory part is loopy. So
595 ;; let's resolve FILENAME's directory part with
596 ;; realpath(3), in order to get a canonical
597 ;; absolute name for the directory, and then
598 ;; return a pathname having PATHNAME's name,
599 ;; type, and version, but the rest from the
600 ;; truename of the directory. Since we turned
601 ;; PATHNAME into FILENAME "as a file", FILENAME
602 ;; does not end in a slash, and so we get the
603 ;; directory part of FILENAME by reparsing
604 ;; FILENAME and masking off its name, type, and
605 ;; version bits. But note not to call ourselves
606 ;; recursively, because we don't want to
607 ;; re-merge against *DEFAULT-PATHNAME-DEFAULTS*,
608 ;; since PATHNAME may be a relative pathname.
611 0
621 filename
625 realpath
630 pathname))
633 ;; If we're still here, the file doesn't exist; error.
636 pathspec errno))))))))
640 #!+sb-doc
641 "Return the truename of PATHSPEC if the truename can be found,
642 or NIL otherwise. See TRUENAME for more information."
646 #!+sb-doc
647 "If PATHSPEC is a pathname that names an existing file, return
648 a pathname that denotes a canonicalized name for the file. If
649 pathspec is a stream associated with a file, return a pathname
650 that denotes a canonicalized name for the file associated with
651 the stream.
653 An error of type FILE-ERROR is signalled if no such file exists
654 or if the file system is such that a canonicalized file name
655 cannot be determined or if the pathname is wild.
657 Under Unix, the TRUENAME of a symlink that links to itself or to
658 a file that doesn't exist is considered to be the name of the
659 broken symlink itself."
660 ;; Note that eventually this routine might be different for streams
661 ;; than for other pathname designators.
667 #!+sb-doc
668 "Return the author of the file specified by PATHSPEC. Signal an
669 error of type FILE-ERROR if no such file exists, or if PATHSPEC
670 is a wild pathname."
674 #!+sb-doc
675 "Return the write date of the file specified by PATHSPEC.
676 An error of type FILE-ERROR is signaled if no such file exists,
677 or if PATHSPEC is a wild pathname."
679 \f
680 ;;;; miscellaneous other operations
685 #!+sb-doc
686 "Rename FILE to have the specified NEW-NAME. If FILE is a stream open to a
687 file, then the associated file is renamed."
694 :pathname new-name
701 :pathname new-name
703 ~I~_~A~:>"
710 #!+sb-doc
711 "Delete the specified FILE."
717 :pathname file
723 t)
724 \f
727 ;; SBCL_HOME isn't set for :EXECUTABLE T embedded cores
735 ;;; (This is an ANSI Common Lisp function.)
737 #!+sb-doc
738 "Return the home directory of the user as a pathname. If the HOME
739 environment variable has been specified, the directory it designates
740 is returned; otherwise obtains the home directory from the operating
741 system."
747 env-home
748 #!-win32
750 #!+win32
751 ;; Needs to bypass PARSE-NATIVE-NAMESTRING & ENSURE-TRAILING-SLASH
752 ;; What?! -- RMK, 2007-12-31
760 \f
761 ;;;; DIRECTORY
765 ;;; NOTE: There is a fair amount of hair below that is probably not
766 ;;; strictly necessary.
767 ;;;
768 ;;; The issue is the following: what does (DIRECTORY "SYS:*;") mean?
769 ;;; Until 2004-01, SBCL's behaviour was unquestionably wrong, as it
770 ;;; did not translate the logical pathname at all, but instead treated
771 ;;; it as a physical one. Other Lisps seem to to treat this call as
772 ;;; equivalent to (DIRECTORY (TRANSLATE-LOGICAL-PATHNAME "SYS:*;")),
773 ;;; which is fine as far as it goes, but not very interesting, and
774 ;;; arguably counterintuitive. (PATHNAME-MATCH-P "SYS:SRC;" "SYS:*;")
775 ;;; is true, so why should "SYS:SRC;" not show up in the call to
776 ;;; DIRECTORY? (assuming the physical pathname corresponding to it
777 ;;; exists, of course).
778 ;;;
779 ;;; So, the interpretation that I am pushing is for all pathnames
780 ;;; matching the input pathname to be queried. This means that we
781 ;;; need to compute the intersection of the input pathname and the
782 ;;; logical host FROM translations, and then translate the resulting
783 ;;; pathname using the host to the TO translation; this treatment is
784 ;;; recursively invoked until we get a physical pathname, whereupon
785 ;;; our physical DIRECTORY implementation takes over.
787 ;;; FIXME: this is an incomplete implementation. It only works when
788 ;;; both are logical pathnames (which is OK, because that's the only
789 ;;; case when we call it), but there are other pitfalls as well: see
790 ;;; the DIRECTORY-HELPER below for some, but others include a lack of
791 ;;; pattern handling.
793 ;;; The above was written by CSR, I (RMK) believe. The argument that
794 ;;; motivates the interpretation is faulty, however: PATHNAME-MATCH-P
795 ;;; returns true for (PATHNAME-MATCH-P #P"/tmp/*/" #P"/tmp/../"), but
796 ;;; the latter pathname is not in the result of DIRECTORY on the
797 ;;; former. Indeed, if DIRECTORY were constrained to return the
798 ;;; truename for every pathname for which PATHNAME-MATCH-P returned
799 ;;; true and which denoted a filename that named an existing file,
800 ;;; (DIRECTORY #P"/tmp/**/") would be required to list every file on a
801 ;;; Unix system, since any file can be named as though it were "below"
802 ;;; /tmp, given the dotdot entries. So I think the strongest
803 ;;; "consistency" we can define between PATHNAME-MATCH-P and DIRECTORY
804 ;;; is that PATHNAME-MATCH-P returns true of everything DIRECTORY
805 ;;; returns, but not vice versa.
807 ;;; In any case, even if the motivation were sound, DIRECTORY on a
808 ;;; wild logical pathname has no portable semantics. I see nothing in
809 ;;; ANSI that requires implementations to support wild physical
810 ;;; pathnames, and so there need not be any translation of a wild
811 ;;; logical pathname to a phyiscal pathname. So a program that calls
812 ;;; DIRECTORY on a wild logical pathname is doing something
813 ;;; non-portable at best. And if the only sensible semantics for
814 ;;; DIRECTORY on a wild logical pathname is something like the
815 ;;; following, it would be just as well if it signaled an error, since
816 ;;; a program can't possibly rely on the result of an intersection of
817 ;;; user-defined translations with a file system probe. (Potentially
818 ;;; useful kinds of "pathname" that might not support wildcards could
819 ;;; include pathname hosts that model unqueryable namespaces like HTTP
820 ;;; URIs, or that model namespaces that it's not convenient to
821 ;;; investigate, such as the namespace of TCP ports that some network
822 ;;; host listens on. I happen to think it a bad idea to try to
823 ;;; shoehorn such namespaces into a pathnames system, but people
824 ;;; sometimes claim to want pathnames for these things.) -- RMK
825 ;;; 2007-12-31.
833 integer)))
835 integer)))
878 ;;; FIXME: written as its own function because I (CSR) don't
879 ;;; understand it, so helping both debuggability and modularity. In
880 ;;; case anyone is motivated to rewrite it, it returns a list of
881 ;;; sublists representing the intersection of the two input directory
882 ;;; paths (excluding the initial :ABSOLUTE or :RELATIVE).
883 ;;;
884 ;;; FIXME: Does not work with :UP or :BACK
885 ;;; FIXME: Does not work with patterns
886 ;;;
887 ;;; FIXME: PFD suggests replacing this implementation with a DFA
888 ;;; conversion of a NDFA. Find out (a) what this means and (b) if it
889 ;;; turns out to be worth it.
943 #!+sb-doc
944 "Return a list of PATHNAMEs, each the TRUENAME of a file that matched the
945 given pathname. Note that the interaction between this ANSI-specified
946 TRUENAMEing and the semantics of the Unix filesystem (symbolic links..)
947 means this function can sometimes return files which don't have the same
948 directory as PATHNAME. If :RESOLVE-SYMLINKS is NIL, don't resolve
949 symbolic links in matching filenames."
951 ;; as an asymptotically efficient way of removing duplicates
952 ;; (which can arise when e.g. multiple symlinks map to the
953 ;; same truename).
955 ;; FIXME: Possibly this MERGE-PATHNAMES call should only
956 ;; happen once we get a physical pathname.
962 ;; FIXME: Why not TRUENAME? As reported by
963 ;; Milan Zamazal sbcl-devel 2003-10-05, using
964 ;; TRUENAME causes a race condition whereby
965 ;; removal of a file during the directory
966 ;; operation causes an error. It's not clear
967 ;; what the right thing to do is, though. --
968 ;; CSR, 2003-10-13
974 filename)))))
987 ;; Sorting isn't required by the ANSI spec, but sorting
988 ;; into some canonical order seems good just on the
989 ;; grounds that the implementation should have repeatable
990 ;; behavior when possible.
996 \f
999 ;;; predicate to order pathnames by; goes by name
1000 ;; FIXME: Does anything use this? It's not exported, and I don't find
1001 ;; the name anywhere else.
1011 xn)))
1012 \f
1014 #!+sb-doc
1015 "Test whether the directories containing the specified file
1016 actually exist, and attempt to create them if they do not.
1017 The MODE argument is a CMUCL/SBCL-specific extension to control
1018 the Unix permission bits."
1036 "~&creating directory: ~A~%"
1037 namestring))
1041 'simple-file-error
1042 :pathname pathspec
1043 :format-control
1044 "can't create directory ~A"
1049 pathspec
1052 :report
1053 "Continue as if directory creation was successful."
1054 nil)))