| Skip Navigation Links | |
| Exit Print View | |
 | man pages section 2: System Calls Oracle Solaris 11 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
| man pages section 2: System Calls Oracle Solaris 11 Information Library |
- change the name of a file
#include <stdio.h>intrename(const char *old,const char *new);
#include <unistd.h>intrenameat(intfromfd,const char *old,inttofd,const char *new);
#include <unistd.h>intrename(const char *old,const char *new);
Therename() function changes the name of a file. Theoldargument points to the pathname of the file to be renamed. Thenew argument points to the new path name of the file.
Therenameat() function renames an entry in a directory, possibly moving theentry into a different directory. Seefsattr(5). If theold argumentis an absolute path, thefromfd is ignored. Otherwise it isresolved relative to thefromfd argument rather than the current working directory. Similarly, if thenew argument is not absolute, it is resolved relativeto thetofd argument. If eitherfromfd ortofd have thevalueAT_FDCWD, defined in <fcntl.h>, and their respective paths are relative, thepath is resolved relative to the current working directory.
Current implementation restrictions will cause therenameat() function to return an errorif an attempt is made to rename an extended attribute file toa regular (non-attribute) file, or to rename a regular file to anextended attribute file.
Ifold andnew both refer to the same existing file, therename() andrenameat() functions return successfully and performs no other action.
Ifold points to the pathname of a file that is nota directory,new must not point to the pathname of a directory.If the link named bynew exists, it will be removed andold will be renamed tonew. In this case, a link namednew must remain visible to other processes throughout the renaming operation andwill refer to either the file referred to bynew or thefile referred to asold before the operation began.
Ifold points to the pathname of a directory,new mustnot point to the pathname of a file that is not adirectory. If the directory named bynew exists, it will be removedandold will be renamed tonew. In this case, a link namednew will exist throughout the renaming operation and will refer toeither the file referred to bynew or the file referredto asold before the operation began. Thus, ifnew names anexisting directory, it must be an empty directory.
Thenew pathname must not contain a path prefix that namesold.Write access permission is required for both the directory containingold andthe directory containingnew. Ifold points to the pathname of adirectory, write access permission is required for the directory named byold, and, if it exists, the directory named bynew.
If the directory containingold has the sticky bit set, atleast one of the following conditions listed below must be true:
the user must ownold
the user must own the directory containingold
old must be writable by the user
the user must be a privileged user
Ifnew exists, and the directory containingnew is writable and hasthe sticky bit set, at least one of the following conditionsmust be true:
the user must ownnew
the user must own the directory containingnew
new must be writable by the user
the user must be a privileged user
If the link named bynew exists, the file's link count becomeszero when it is removed, and no process has the file open,then the space occupied by the file will be freed andthe file will no longer be accessible. If one or more processeshave the file open when the last link is removed, the link willbe removed beforerename() orrenameat() returns, but the removal of thefile contents will be postponed until all references to the file havebeen closed.
Upon successful completion, therename() andrenameat() functions will mark for updatethest_ctime andst_mtime fields of the parent directory of each file.
Upon successful completion,0 is returned. Otherwise,-1 is returned anderrnois set to indicate an error.
Therename() function will fail if:
A component of either path prefix denies search permission; one of the directories containingold andnew denies write permissions; or write permission is denied by a directory pointed to byold ornew.
Thenew orold argument is a directory and the mount point for a mounted file system.
The directory where the new name entry is being placed cannot be extended because the user's quota of disk blocks on that file system has been exhausted.
The link named bynew is a directory containing entries other than `.' (the directory itself) and `..' (the parent directory).
Eitherold ornew references an invalid address.
The path argument includes non-UTF8 characters and the file system accepts only file names where all characters are part of the UTF-8 character codeset.
Thenew argument directory pathname contains a path prefix that names theold directory, or an attempt was made to rename a regular file to an extended attribute or from an extended attribute to a regular file.
An I/O error occurred while making or updating a directory entry.
Thenew argument points to a directory butold points to a file that is not a directory.
Too many symbolic links were encountered in translating the pathname.
The length ofold ornew exceedsPATH_MAX, or a pathname component is longer thanNAME_MAX while_POSIX_NO_TRUNC is in effect.
The file named byold is a directory, and the link count of the parent directory ofnew would exceedLINK_MAX.
The link named byold does not name an existing file, a component of the path prefix ofnew does not exist, or eitherold ornew points to an empty string.
The directory that would containnew cannot be extended.
A component of either path prefix is not a directory, orold names a directory andnew names a file that is not a directory, ortofd anddirfd inrenameat() do not reference a directory.
The requested operation requires writing in a directory on a read-only file system.
The links named byold andnew are on different file systems.
Therenameat() functions will fail if:
An attempt was made to rename a regular file as an attribute file or to rename an attribute file as a regular file.
Seeattributes(5) for descriptions of the following attributes:
|
chmod(2),link(2),unlink(2),attributes(5),fsattr(5),standards(5)
The system can deadlock if there is a loop in the filesystem graph. Such a loop can occur if there is an entryin directorya,a/name1, that is a hard link to directoryb,and an entry in directoryb,b/name2, that is a hard link todirectorya. When such a loop exists and two separate processes attemptto renamea/name1 tob/name2 andb/name2 toa/name1, the system maydeadlock attempting to lock both directories for modification. Use symbolic linksinstead of hard links for directories.
Copyright © 2011, Oracle and/or its affiliates. All rights reserved.Legal Notices |   |