<< Previous | Next >>

fcreate (FS2)

int fcreate( File* f, FileNumber name );

Description

Create a new file with the given "file name" which is composed of two parts: the low byte is the actual file number (1 to 255 inclusive), and the high byte contains an extent number (1 to _fs.num_lx) on which to place the file metadata. The extent specified by fs_set_lx() is always used to determine the actual data extent. If the high byte contains 0, then the default metadata extent specified by fs_set_lx() is used. The file descriptor is filled in if successful. The file will be opened for writing, so a further call to fopen_wr() is not necessary.

The number of files which may be created is limited by the lower of FS_MAX_FILES and 255. This limit applies to the entire filesystem (all logical extents). Once a file is created, its data and metadata extent numbers are fixed for the life of the file, i.e., until the file is deleted.

When created, no space is allocated in the file system until the first write occurs for the file. Thus, if the system power is cycled after creation but before the first byte is written, the file will be effectively deleted. The first write to a file causes one sector to be allocated for the metadata.

Before calling this function, a variable of type File must be defined in the application program. (The sizeof() function will return the number of bytes used for the File data structure.)

   

File file;
fcreate (&file, 1);

Parameters

f

Pointer to the file descriptor to fill in.

name

File number including optional metadata extent number.

Return value

 0: Success.
!0: Failure.

ERRNO values

EINVAL - Zero file number requested, or invalid extent number.
EEXIST - File with given number already exists.
ENFILE - No space is available in the existing file table. If this error occurs, increase the definition of FS_MAX_FILES, a #define constant that should be declared before #use "fs2.lib".

Library

fs2.LIB

See also

fcreate_unused (FS2), fs_set_lx (FS2), fdelete (FS2)