File System User API

Transcription

1 File System User API Blunk Microsystems file system API includes the file-related routines from Standard C and POSIX, as well as a number of non-standard functions that either meet a need unique to embedded systems programming or provide a convenience or optimization. The supplied library supports all commonly needed file operations. Either 'posix.h' or 'stdio.h' must be included to use the routines, as indicated on the user s guide. Except for rename(), the Standard C API is a subset of the POSIX API in regard to functionality. There is some overlap. For example, write() from the POSIX API is similar to the Standard C fwrite(). The directory-related routines (mkdir(), etc.) are all from the POSIX API. In the following functional grouping, the API routine names are color-coded based on whether a stream handle ("FILE *"), descriptor ("int"), pathname, or neither is used to specify the file they act on. Descriptor-Stream Conversion fdopen() - convert descriptor to stream fileno() - convert stream to descriptor Directory Management chdir() - change working directory closedir() - close directory list frstat() - fstat() with directory size getcwd() - get current working directory mkdir() - create new directory opendir() - open directory list readdir() - read from directory list readdir_fopen() - readdir() and fopen() readdir_open() - readdir() and open() readdir_stat() - readdir() and stat() rewinddir() - reset directory list rmdir() - remove directory rstat() - stat() with directory size sortdir() - sort directory file list unlink_all() - remove all directory contents The rstat() routines recursively calculate directory size. readdir_xxx() uses the DIR handle returned by opendir() to quickly complete the second function without any file name lookup. sortdir() reorders a directory's file list. unlink_all() is a fast way to empty a directory. Environment fpathconf() - get configuration value pathconf() - get configuration value 2-1

2 2 Application Program Interface FAT Label Access FatReadLabel() - Read FAT volume label FatWriteLabel() - Write FAT volume label These routines allow applications to read and write the volume label. The volume label is either the root directory label, if it exists, or the Volume Boot Record label. File Attributes attribute() - set/read file attributes File attributes are 32-bit values. Each file has its own attribute bits. Attribute bits can be read and set independently. They have application-dependent meanings only. The file system does not interpret the attribute bits in any way. File Information/Permissions/Status access() - determine file accessibility chmod() - change file permissions chown() - change file UID/GID clearerr() - reset EOF/error indicators ctime_set() - set file creation time feof() - test EOF indicator ferror() - test file error indicator fstat() - get file information fstat_set() - set file times/permissions isatty() - test if file is device is_open() - test if file is open setbuf() - affect I/O buffering setvbuf() - affect I/O buffering stat() - get file information stat_set() - set file times/permissions utime() - set access/mod times File Input fgetc() - read character from file fgets() - read string from file fread() - read from file fscanf() - formatted read from file getc() - read character from file getchar() - read character from stdin gets() - read string from stdin read() - read from file scanf() - formatted read from stdin ungetc() - undo last char read File Length/Position fgetpos() - get file offset 2-2

3 Application Program Interface 2 fseek() - set file offset fsetpos() - set file offset ftell() - get file offset fresize() - set file length without zero-filling extensions ftruncate() - set file length lseek() - set file offset resize() - set file length without zero-filling extensions rewind() - reset file offset truncate() - set file length File Numbers fid2fileno() - get file number from file descriptor getfileno() - get file number from file path getfname() - set file name from file number getpath() - get path name from number File numbers are a way to reduce both a file name and its path to a 32-bit persistent number. The association between a file number and the file s name and path is valid even for closed files, allowing 32-bit database entries to refer to file names and paths of arbitrary length. File Open/Close/Create/Delete/Rename close() - close file close_unlink() - close file and then remove file path creat() - create a new file dup() - duplicate open file descriptor dup2() - open file reusing descriptor fclose() - close file fcntl() - affect open file descriptor fopen() - open file freopen() - open file reusing stream link() - create additional path to file mmap() - map a file into memory open() - open a file remove() - remove file path rename() - rename file shred() - remove file and overwrite prior contents unlink() - remove file path File Output fprintf() - formatted write to file fputc() - write character to file fputs() - write string to file fwrite() - write to file perror() - write error message to stderr printf() - formatted write to stdout putc() - write character to file putchar() - write character to stdout 2-3

4 2 Application Program Interface puts() - write string to stdout vfprintf() - write vargs to file vprintf() - write vargs to stdout write() - write to file Quotas get_quota() - get quota/free information quota_info() - get quota info structure mkdirq() - mkdir() with quotas The quota routines allow directories to be created with a pre-defined maximum size and/or a size reservation. File writes within a quota-capped directory receive the volume full indication if the maximum directory size is reached. Also, file writes receive the volume full indication if the volume is full when considering all directories with reservations to be at their maximum size. Seek Acceleration fseekmark() - mark offset for later seek lseekmark() - mark offset for later seek The seek mark functions allow file seeks to start from either the beginning of a file, its end, the current position, or a specially marked offset, whichever is closest to the final position. Synchronization disable_sync() - disable synchronizations enable_sync() - enable synchronizations The synchronization routines control whether synchronizations are triggered by the routines listed under "Synchronization" in Chapter 3 of this manual. They are only helpful if the volume's FSF_SYNC_ON flag is set. Otherwise, synchronization is not triggered by API calls other than fflush(), fsync(), sync(), and unmount() and these synchronizations cannot be disabled. Temporary File/Name tmpfile() - create temporary file tmpnam() - create unique file name Unicode Related is_utf8() - test if valid UTF8 string utf8_utf16() - convert UTF8 to UTF16 utf16_utf8() - convert UTF16 to UTF8 Volume Management fflush() - store buffered data fsync() - store buffered data format() - erase/prepare volume 2-4

5 Application Program Interface 2 mount() - make volume accessible mount_all() - mount all attached volumes sync() - store buffered data unformat() - erase all (good) flash sectors unmount() - free volume memory vclean() - clean dirty flash sectors viter_next() - advance pos in volume name list viter_reset() - reset pos in volume name list vmemgb() - recover unused name memory vstat() - get volume information vsync() - store volume's buffered data mount_all() mounts all volumes that have been added, but not mounted. unformat() completely erases a volume. This is needed before redefining a volume in terms of block size, number of blocks, etc. vclean() performs background garbage collection. vmemgb() recovers unused memory, if available, from the memory manager used to store file names. Volume Sector Interface FatVolClose() - free volume handle FatVolOpen() - open volume handle FatVolNumSectors() - return number of volume sectors FatVolReadSectors() - read volume sectors FatVolSync() - sync volume data FatVolWriteSectors() - write volume sectors These routines provide a read sector/write sector interface to the specified volume. This interface is provided to support USB Mass Storage Device drivers performing PC file sharing. Only unmounted volumes can be opened by FatVolOpen() and volumes thus opened cannot be mounted until FatVolClose() is called. 2-5