File Manager

The file manager supports routines for opening and creating files, reading data from and writing data to files, and closing files. In addition, you can manipulate the end-of-file mark of a file and position the current read or write mark to an arbitrary position in the file. You also can move, copy, and rename files, determine and set file characteristics, and delete files.

The file manager contains a number of routines for directories, with which you can create and delete directories. You also can determine and set directory characteristics and obtain a list of a directory's contents.

LabVIEW supports concurrent access to the same file, so you can have a file open for both reading and writing simultaneously. When you open a file, you can indicate whether you want the file to be read from and written to concurrently. You also can lock a range of the file, if you need to make sure a range is nonvolatile at a given time.

The file manager also provides many routines for manipulating paths, or path names, in a platform-independent manner. The file manager supports the creation of path descriptions, which are either relative to a specific location or absolute, that is, the full path. With file manager routines you can create and compare paths, determine characteristics of paths, and convert a path between platform-specific descriptions and the platform-independent form.

Applications that manipulate files can use the functions in the file manager. The file manager routines support basic file operations such as creating, opening, and closing files, writing data to files, and reading data from files. In addition, you can use file manager routines to create directories, determine characteristics of files and directories, and copy files. File manager routines use a LabVIEW data type for file path names, called Paths, that indicates a file or directory path independent of the platform. You can translate a Path to and from the conventional format a host platform uses for describing a file pathname.

Identifying Files and Directories

When you perform operations on files and directories, you need to identify the target of the operation. The platforms LabVIEW supports use a hierarchical file system, meaning files are stored in directories, possibly nested several levels deep. These hierarchical file systems support the connection of multiple discrete storage media, called volumes. For example, DOS-based systems support multiple drives connected to the system. For most of these hierarchical file systems, you must include the volume name to specify the location of a file. On other systems, such as Linux, you do not need to specify the volume name because the physical implementation of the file system is hidden from the user.

How you identify a target depends upon whether the target is an open or closed file. If a target is a closed file or a directory, specify the target using the path of the target. The path describes the volume containing the target, the directories between the top level and the target, and the name of the target. If the target is an open file, use a file descriptor to specify that LabVIEW should perform an operation on the open file. The file descriptor is an identifier the file manager associates with the file when you open it. When you close the file, the file manager dissociates the file descriptor from the file.

Path Specifications

LabVIEW uses the following types of file path specifications:

Conventional

All platforms have a method for describing the paths for files and directories. These path specifications are similar, but they are usually incompatible from one platform to another. You usually specify a path as a series of names separated by separator characters. Typically, the first name is the top level of the hierarchical specification of the path. The last name is the file or directory the path identifies.

A path can be one of the following types:

A relative path describes the location of a file or directory relative to an arbitrary location in the file system. An absolute path describes the location of a file or directory starting from the top level of the file system.

A path does not necessarily go from the top of the hierarchy down to the target. You can often use a platform-specific tag in place of a name that indicates the path should go up a level from the current location.

(OS X 64-bit and Linux) You specify the path of a file or directory as a series of names separated by the slash (/) character. If the path is an absolute path, you begin the specification with a slash. Indicate the path should move up a level using two periods in a row (..). Thus, the following path specifies a file readme relative to the top level of the file system, where username is the user directory:

/usr/home/username/myapps/readme

The following paths are two relative paths to the same file:

username/myapps/readme relative to /usr/home
../myapps/readme relative to a directory inside of the username directory

(Windows) You separate names in a path with a backslash (\) character. If the path is an absolute path, you begin the specification with a drive designation, followed by a colon (:), followed by the backslash. Indicate the path should move up a level using two periods in a row (..). Thus, the following path specifies a file readme relative to the top level of the file system, on a drive named C:

c:\home\username\myapps\readme

The following paths are two relative paths to the same file:

username\myapps\readme relative to the home directory
..\myapps\readme relative to a directory inside of the username directory

(OS X 32-bit) You separate names in a path with the colon (:) character. If the path is an absolute path, you begin the specification with the name of the volume containing the file. If an absolute path consists of only one name, that is, it specifies a volume, the path must end with a colon. If the path is a relative path, it begins with a colon. The colon is optional for a relative path consisting of only one name. Indicate the path should move up a level using two colons in a row (::). Thus, the following path specifies a file readme relative to the top level of the file system, on a drive named hard drive:

hard drive:home:username:myapps:readme

The following paths are two relative paths to the same file:

:username:myapps:readme relative to the home directory
::myapps:readme relative to a directory inside of the username directory

Empty

You can define a path with no names, called an empty path. An empty path is either absolute or relative. An absolute path contains the complete address of a file's location within the file hierarchy. An empty absolute path refers to the highest point in the file hierarchy. A relative path contains the address of a file's location relative to the position of the user within the file hierarchy. An empty relative path refers to the current position of the user within the file hierarchy.

(OS X 64-bit and Linux) A slash (/) represents the empty absolute path. The slash specifies the root of the file hierarchy. A period (.) represents the empty relative path.

(Windows) You represent the empty absolute path as an empty string. The empty absolute path specifies the set of all volumes on the system. A period (.) represents the empty relative path.

(OS X 32-bit) The empty absolute path is represented as an empty string. The absolute path specifies the set of all volumes on the system. A colon (:) represents the empty relative path.

LabVIEW

In LabVIEW, you specify a path using a special LabVIEW data type, represented as Path. The exact structure of the Path data type is private to the file manager. You create and manipulate the Path data type using file manager routines.

A Path is a dynamic data structure. Just as you use memory manager routines to allocate and deallocate handles and pointers, you use file manager routines to create and deallocate a Path. Just as with handles, declaring a Path variable does not actually create a Path. Before you can use the Path to manipulate a file, you must dynamically allocate the Path using file manager routines. When you are finished using the Path variable, you should release the Path using file manager routines.

In addition to providing routines for the creation and elimination of a Path, the file manager provides routines for comparing, duplicating, determining Path characteristics, and converting Path to and from other formats, such as the platform-specific format for the system on which LabVIEW is running.

File Descriptors

When you open a file, LabVIEW returns a file descriptor associated with the file. A file descriptor is a data type LabVIEW uses to identify open files. All operations performed on an open file use the file descriptor to identify the file.

A file descriptor is valid only while the file is open. If you close the file, the file descriptor is no longer associated with the file. If you open the file again, the new file descriptor is most likely different from the previous file descriptor.

File Refnums

In the file manager, LabVIEW accesses open files using file descriptors. However, on the front panel and block diagram, LabVIEW accesses open files using file refnums. A file refnum contains a file descriptor for use by the file manager and additional information used by LabVIEW.

LabVIEW specifies file refnums using the LVRefNum data type, the exact structure of which is private to the file manager. To pass references to open files into a shared library, convert file refnums to file descriptors with the FRefNumToFD LabVIEW Manager function. To pass references to open files out of a shared library, convert file descriptors to file refnums with the FNewRefNum LabVIEW Manager function.