FunctionPackage: exclToCDocOverviewCGDocRelNotesFAQIndexPermutedIndex
Allegro CL version 8.1
Unrevised from 8.0 to 8.1.
8.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-2009, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 8.1. This page was not revised from the 8.0 page.
Created 2009.7.29.

Allegro CL version 8.1
Unrevised from 8.0 to 8.1.
8.0 version