#$EPIC: rename,v 1.4 2003/07/05 06:34:00 jnelson Exp $
Synopsis:
   $rename(<oldpath> <newpath>)

Technical:
   * If the <oldpath> or <newpath> arguments are omitted this function
     returns the empty string.
   * The file <oldpath> is renamed to <newpath> in accordance with the
     rename(2) system call on your operating system.
   * Generally speaking $rename cannot move files between file systems,
     but they can be moved between directories on the same file system.

Practical:
   Naturally, this function is useful any time a file needs to be renamed.
   One use for it might be to back up your .ircrc before doing a SAVE, just
   in case something goes wrong before the command is completed.

Returns:
    0   file renamed successfully
   -1   error during rename attempt

Examples:
   $rename(~/.ircrc ~/.ircrc.bak)              returns 0 if successful
   $rename(/etc/passwd /etc/hahaha)            probably will return -1

History:
   This function first appeared in EPIC2.

See Also:
   fexist(6); unlink(6)

