FunctionPackage: exclToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version


Arguments: filespec new-name &key follow-symlinks

The function is similar to cl:rename-file in that it renames the file or directory specified by the filespec to the file or directory specified by the new-name argument. The truename of the renamed file is returned, as a symbolic link (if it is one) if follow-symlinks is nil (the default) and as the canonical filename if follow-symlinks is true. (rename-file-raw calls truename passing the value of follow-symlinks. See Extensions to cl:make-package, cl:disassemble, cl:truename, cl:probe-file, cl:open, cl:apropos in implementation.htm.)

rename-file-raw differs from cl:rename-file in that it mimics the UNIX mv/Windows MOVE method of resolving relative pathnames when renaming files. If new-name is a relative pathname, it is merged with *default-pathname-defaults* to get the actual new name. cl:rename-file merges new-name with filespec. The difference can be seen with the following example:

;; *default-pathname-defaults* is an absolute pathname and
;; both directories /usr/home/user1/tmp/ and 
;; /usr/home/user1/tmp/tmp/ exist.
  -> #p"/usr/home/user1/"

(probe-file "tmp/") -> #p"/usr/home/user1/tmp/"
(probe-file "tmp/tmp/") -> #p"/usr/home/user1/tmp/tmp/"

;;  Only one of the following four forms may be evaluated, 
;;  since after evaluation the file specified by 
;;  the first argument will not exist.
;;  Only the first value returned is shown.

(rename-file "tmp/" "tmp/")
  -> #p"/usr/home/user1/tmp/tmp/"
(rename-file-raw "tmp/" "tmp/")
  -> #p"/usr/home/user1/tmp/"

(rename-file "tmp/" "")
  -> #p"/usr/home/user1/tmp/"
(rename-file-raw "tmp/" "")
  -> #p"/usr/home/user1/"

Like cl:rename-file, rename-file-raw returns three values: The new name, the truename of filespec, and the truename of the new name. Here is the source, followed by the source of cl:rename-file:

(defun rename-file-raw (filespec new-name)
  (let ((new-name (pathname new-name))
	(old-truename (truename filespec)))
    (excl::filesys-rename-file (namestring old-truename)
			   (translate-logical-pathname new-name))))
    (values new-name old-truename (truename new-name))))

(defun rename-file (filespec new-name)
  (let ((defaulted-new-name (merge-pathnames new-name filespec))
	(old-truename (truename filespec)))
    (excl::filesys-rename-file (namestring old-truename)
			 (namestring (translate-logical-pathname
				      (pathname defaulted-new-name))))
    (values defaulted-new-name old-truename
	    (truename defaulted-new-name))))

The situation in release 6.1 was confused, because the behavior of cl:rename-file depended on the value of *default-pathname-defaults* in inappropriate ways (when *default-pathname-defaults* was an absolute pathname, 6.1 cl:rename-file worked like the new rename-file-raw; when *default-pathname-defaults* was an empty pathname -- #p"", 6.1 cl:rename-file worked as specified by ANSI, that is, as cl:rename-file works now. An additional function, rename-file-acl6.1 is provided which is the Allegro CL 6.1 implementation of cl:rename-file. Users who want the exact 6.1 behavior can use it.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.

Allegro CL version 10.1
Unrevised from 10.0 to 10.1.
10.0 version