Open System Services System Calls Reference Manual (G06.25+, H06.03+)

System Functions (r) rename_oss(2)
If the from and to parameters specify directories, the following requirements exist:
• The directory specified by the from parameter must not be an ancestor of the directory
specified by the to parameter. For example, the to pathname must not contain a path-
name prefix that specifies from.
• The directory specified by the to parameter must be empty, except for the . (dot) and ..
(dot-dot) entries.
Upon successful completion (where a rename occurs), the function marks the st_ctime and
st_mtime fields of the parent directory of each file for update.
Use on Guardian Objects
The OSS rename() function can be used on Guardian files (that is, files within /G). The OSS
rename() function cannot be used on directories within /G. The new pathname must correspond
to a Guardian permanent disk file name on the same volume, and the caller must have Guardian
write access to the file.
A call to rename a file in /G is implemented as the following sequence of Guardian procedure
calls:
FILE_OPEN_ with read access and shared exclusion
FILE_RENAME_
FILE_CLOSE_
Use From the Guardian Environment
The OSS rename() function belongs to a set of functions that have the following effects when
the first of them is called from the Guardian environment:
• Two Guardian file-system file numbers (not necessarily the next two available) are allo-
cated for the root directory and the current working directory. These file numbers cannot
be closed by calling the Guardian FILE_CLOSE_ procedure.
• The current working directory is assigned from the VOLUME attribute of the Guardian
environment =_DEFAULTS DEFINE.
• The use of static memory by the process increases slightly.
These effects occur only when the first of the set of functions is called. The effects are not cumu-
lative.
Interoperability Variants
The C run-time library supports two variants of the rename() function: rename_oss() and
rename_guardian(). The variants support the unique file-naming conventions and structures of
the OSS and Guardian file systems, respectively.
The header file maps calls to rename() to the variant that matches the target compilation
environment. The target environment is set with the systype pragma.
Explicit calls to the rename_oss() and rename_guardian() variants in source code are made
only when the behavior of one environment is desired from the other environment.
rename_oss() is functionally identical to the rename() function of the OSS environment. It is
the same as setting systype oss at compile time. systype oss is the default setting for use
of the c89 utility in the OSS environment.
rename_guardian() is functionally identical to the rename() function of the Guardian environ-
ment. It is the same as setting systype guardian at compile time. systype guardian is the
default setting for the C and C++ compilers in the Guardian environment.
527186-003 Hewlett-Packard Company 6−27