FreeBasic Name Keyword

Last modified October 18, 2026

The FreeBasic Name function renames a file or folder on disk. It takes the old name and the new name as arguments and returns zero on success and a non-zero value on failure.

Basic Definition

In FreeBasic, Name is a function with the syntax result = Name(oldname, newname). It operates on the file system, not on program variables. It does not create aliases for variables, functions, or types; the older Name old As new alias form is not valid FreeBasic.

Because Name is a function, the separator between the two names is a comma, not As. The Name function can also move a file to a different directory, as long as both paths are valid.

Renaming a File

This example renames a file in the current directory. The file is first created with Open, then renamed with Name. The FileExists function, which requires file.bi, is used to check the result.

name_file2.bas

#include "file.bi"

Dim r As Long
Open "a.txt" For Output As #1
Close #1
r = Name("a.txt", "b.txt")
Print "rename result: "; r
Print "exists b: "; FileExists("b.txt")
Kill "b.txt"

The program creates a.txt, renames it to b.txt, and prints the return value followed by the result of FileExists. The output is rename result: 0 and exists b: -1, where 0 means success and -1 is the value of a true FileExists test. The final Kill removes the renamed file.

Moving a File to Another Directory

The Name function can move a file across directories by giving a path with a different folder as the new name.

name_file3.bas

#include "file.bi"

Dim r As Long
Open "src_dir.txt" For Output As #1
Close #1
Mkdir "dstdir"
r = Name("src_dir.txt", "dstdir/moved.txt")
Print "cross-dir result: "; r; " exists: "; FileExists("dstdir/moved.txt")
Kill "dstdir/moved.txt"
RmDir "dstdir"

The file src_dir.txt is moved into the dstdir folder and renamed to moved.txt. The output is cross-dir result: 0 exists: -1. The program then removes the moved file and the folder.

Checking the Return Value

Renaming a file that does not exist fails, and Name returns a non-zero value. Checking the return value lets a program detect this.

name_file.bas

#include "file.bi"

Dim r As Long
Open "old_name.txt" For Output As #1
Print #1, "hello"
Close #1
Mkdir "subdir"
r = Name("old_name.txt", "subdir/new_name.txt")
Print "result: "; r
Print "exists moved: "; FileExists("subdir/new_name.txt")
Print "exists old: "; FileExists("old_name.txt")
r = Name("missing.txt", "x.txt")
Print "missing result: "; r

The first rename succeeds and returns 0; the file is then present in subdir and no longer at its old location. Renaming the nonexistent missing.txt returns -1 on this system, which is a non-zero failure value.

Best Practices

Check the result: Always test the return value of Name for a non-zero failure.
Existing targets: If the new name already exists, Name may overwrite it or fail. Use FileExists and Kill first when this matters.
Syntax: Use a comma between the old and new names, not As.
Paths: Use paths that exist; create destination folders with Mkdir beforehand.

This tutorial covered the FreeBasic Name function, which renames and moves files on disk, and showed how to check its return value.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all FreeBasic Tutorials.