Gives a new name to an existing file.

    Format

      #include  <stdio.h>

      int rename  (const char *old_file_spec, const char
                  *new_file_spec);

1  –  Arguments

 old_file_spec

    A pointer to a string that is the existing name of the file to be
    renamed.

 new_file_spec

    A pointer to a string that is to be the new name of the file.

2  –  Description

    If you try to rename a file that is currently open, the behavior
    is undefined. You cannot rename a file from one physical device
    to another. Both the old and new file specifications must reside
    on the same device.

    If the new_file_spec does not contain a file extension, the
    file extension of old_file_spec is used. To rename a file to
    have no file extension, new_file_spec must contain a period
    (.)  For example, the following renames SYS$DISK:[]FILE.DAT to
    SYS$DISK:[]FILE1.DAT:

    rename("file.dat", "file1");

    However, the following renames SYS$DISK:[]FILE.DAT to
    SYS$DISK:[]FILE1:

    rename("file.dat", "file1.");

                                   NOTE

       Because the rename function does special processing of the
       file extension, the caller must be careful when specifying
       the name of the renamed file in a call to a C Run-Time
       Library function that accepts a file-name argument. For
       example, after the following call to the rename function,
       the new file should be opened as fopen("bar.dat",...):

       rename("foo.dat", "bar");

    The rename function is affected by the setting of the
    DECC$RENAME_NO_INHERIT and DECC$RENAME_ALLOW_DIR feature logicals
    as follows:

    o  DECC$RENAME_NO_INHERIT provides more UNIX compliant behavior
       in rename, and affects whether or not the new name for the
       file inherits anything (like file type) from the old name or
       must be specified completely.

    o  DECC$RENAME_ALLOW_DIR lets you choose between the previous
       OpenVMS behavior of allowing the renaming of a file from one
       directory to another, or the more UNIX compliant behavior of
       not allowing the renaming of a file to a directory.

    Also see the C RTL help for feature logicals DECC$RENAME_NO_
    INHERIT and DECC$RENAME_ALLOW_DIR.

3  –  Return Values

    0                  Indicates success.
    -1                 Indicates failure. The function sets errno to
                       one of the following values:

                       o  EISDIR - The new argument points to a
                          directory, and the old argument points
                          to a file that is not a directory.

                       o  EEXIST - The new argument points to a
                          directory that already exists.

                       o  ENOTDIR - The old argument names a
                          directory, and new argument names a non-
                          directory file.

                       o  ENOENT - The old argument points to a file,
                          directory, or device that does not exist.

                          Or the new argument points to a nonexisting
                          directory path or device.