FreeBasic ChDir Keyword

Last modified October 18, 2026

The FreeBasic ChDir keyword changes the current working directory. It allows programs to navigate the file system and access files in different locations. This is essential for file operations in specific directories.

Basic Definition

ChDir is a FreeBasic function that changes the current working directory to the specified path. The path can be absolute or relative to the current directory. It affects subsequent file operations in the program.

The function requires a valid directory path string. It returns 0 on success and -1 on failure. If the path does not exist, no runtime error is raised and the current directory remains unchanged, so the return value must be checked. Always verify the result of ChDir for robust programs.

Changing to an Absolute Directory

This example demonstrates changing to an absolute directory path.

chdir_absolute.bas

Print "Current directory: "; CurDir

' Change to an absolute path
ChDir "C:\Users\Public\Documents"

Print "New directory: "; CurDir

The code first prints the current directory using CurDir. Then it changes to a specific absolute path using ChDir. Finally, it verifies the change by printing the new current directory.

Changing to a Relative Directory

This example shows how to navigate using relative paths.

chdir_relative.bas

Print "Current directory: "; CurDir

' Change to a subdirectory
ChDir "subfolder"

Print "After moving down: "; CurDir

' Move back up
ChDir ".."

Print "After moving up: "; CurDir

The program first moves into a subdirectory called "subfolder". Then it moves back to the parent directory using "..". Relative paths are useful when you know the directory structure relative to your program.

Error Handling with ChDir

This example demonstrates proper error handling when changing directories.

chdir_error.bas

Dim newPath As String = "C:\nonexistent\folder"

Print "Attempting to change to: "; newPath
If ChDir(newPath) = 0 Then
    Print "Successfully changed directory"
Else
    Print "Could not change to directory: "; newPath
End If

The code attempts to change to a non-existent directory. ChDir returns -1 on failure, so the program checks the return value and displays a message when the change did not succeed. No runtime error is raised.

ChDir with User Input

This example shows interactive directory changing based on user input.

chdir_interactive.bas

Print "Current directory: "; CurDir
Dim path As String
Input "Enter directory path to change to: ", path

If ChDir(path) = 0 Then
    Print "Successfully changed to: "; CurDir
Else
    Print "Invalid directory: "; path
End If

The program prompts the user for a directory path. It then attempts to change to that directory and checks the return value. If successful, it confirms the change. If not, it displays an error message. This demonstrates dynamic directory navigation.

ChDir in Combination with File Operations

This example shows practical use of ChDir with file operations.

chdir_fileops.bas

' Save original directory
Dim originalDir As String = CurDir

' Change to target directory
If ChDir("C:\Temp") <> 0 Then Print "Could not change to C:\Temp"

' Create and write to a file in the new directory
Open "testfile.txt" For Output As #1
Print #1, "This file was created after ChDir"
Close #1

' Return to original directory
ChDir originalDir

Print "File created in: C:\Temp\testfile.txt"
Print "Restored to original directory: "; CurDir

The code first saves the original directory. It then changes to a temporary directory and creates a file there. Finally, it returns to the original directory. This pattern is useful for temporary directory changes.

ChDir with Multiple Directory Levels

This example demonstrates navigating through multiple directory levels.

chdir_multilevel.bas

Print "Starting directory: "; CurDir

' Change to first level
ChDir "subfolder1"
Print "Level 1: "; CurDir

' Change to second level
ChDir "subfolder2"
Print "Level 2: "; CurDir

' Jump back to starting point
ChDir "../.."
Print "Back to start: "; CurDir

The program navigates down two directory levels, printing the current directory at each step. Then it uses a relative path with multiple ".." to return to the starting directory in one operation. On Windows, backslashes and forward slashes are both accepted; on Linux, only forward slashes work.

ChDir with Network Paths

This example shows how to work with network shared folders.

chdir_network.bas

Dim networkPath As String = "\\server\share\folder"

Print "Attempting to access network path..."
If ChDir(networkPath) = 0 Then
    Print "Successfully changed to network directory: "; CurDir
    ' Perform file operations here...
Else
    Print "Failed to access network path: "; networkPath
End If

The code attempts to change to a network shared folder. Network paths require proper permissions and connectivity. The example checks the return value of ChDir so it handles cases where the network resource is unavailable.

Best Practices

Error Handling: Always check the return value of ChDir (0 on success, -1 on failure).
Restore Directory: Consider saving and restoring the original directory.
Path Validation: Verify paths exist before attempting to change.
Relative Paths: Use relative paths when possible for portability.
Network Paths: Handle network paths with extra care and timeouts.

This tutorial covered the FreeBasic ChDir keyword with practical examples showing directory navigation in different scenarios.

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.

Ebooks