rename()--Rename File or Directory

 #include <Qp0lstdi.h>

 int rename(const char *old, const char *new);  

The rename() function can be defined to be either Qp0lRenameUnlink() or Qp0lRenameKeep(), depending upon the definitions of the _POSIX_SOURCE and _POSIX1_SOURCE macros in the <Qp0lstdi.h> header file:

• When _POSIX_SOURCE or _POSIX1_SOURCE is defined, rename() is defined to be Qp0lRenameUnlink(). Either rename() or Qp0lRenameUnlink() can be used to rename a file or directory with the semantics of Qp0lRenameUnlink().
  
• When _POSIX_SOURCE and _POSIX1_SOURCE are not defined, rename() is defined to be Qp0lRenameKeep(). Either rename() or Qp0lRenameKeep() can be used to rename a file or directory with the semantics of Qp0lRenameKeep().

When the <Qp0lstdi.h> header file is not included, rename() operates only on database files in the QSYS.LIB or independent ASP QSYS.LIB file system, as it did before the introduction of the integrated file system.

For details on the use of rename(), see the Qp0lRenameUnlink() and Qp0lRenameKeep() functions.

Note: The rename() function is implemented using either the Qp0lRenameUnlink() or the Qp0lRenameKeep() function. When using ILE languages such as RPG, COBOL, and CL, developers need to specify Qp0lRenameUnlink or Qp0lRenameKeep as the external name of the API, whichever is appropriate.

Authorities and Locks

None.

Parameters

old

(Input) A pointer to the null-terminated path name of the file to be renamed.

This parameter is assumed to be represented in the CCSID (coded character set identifier) currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

new

(Input) A pointer to the null-terminated path name of the new name of the file.

This parameter is assumed to be represented in the CCSID currently in effect for the job. If the CCSID of the job is 65535, this parameter is assumed to be represented in the default CCSID of the job.

The new file name is assumed to be represented in the language and country or region currently in effect for the process.

Usage Notes

1. This function will fail with error code [ENOTSAFE] when all the following conditions are true:
   • Where multiple threads exist in the job.
     
   • The object on which this function is operating resides in a file system that is not threadsafe. Only the following file systems are threadsafe for this function:
     • "Root" (/)
     • QOpenSys
     • User-defined
     • QNTC
     • QSYS.LIB
     • Independent ASP QSYS.LIB
     • QOPT
     • Network File System
     • QFileSvr.400

Related Information

• The <stdio.h> file (see Header Files for UNIX^®-Type Functions)
  
• The <Qp0lstdi.h> file (see Header Files for UNIX-Type Functions)
  
• pathconf()--Get Configurable Path Name Variables
  
• Qp0lRenameKeep()--Rename File or Directory, Keep "new" If It Exists
  
• Qp0lRenameUnlink()--Rename File or Directory, Unlink "new" If It Exists

[ Back to top | UNIX-Type APIs | APIs by category ]