File System POSIX API#
_fs_errno()#
Description#
Converts file system error code into Posix error code.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int _fs_errno (void)Arguments#
Returned Value#
Posix error code.
Notes / Warnings#
None.
fs_perror()#
Description#
Print POSIX error code along with user's output string.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
void fs_perror (const char *p_err_desc)Arguments#
p_err_desc
Pointer to the user output string.
Returned Value#
none.
Notes / Warnings#
None.
fs_chdir()#
Description#
Set the working directory for the current task.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_chdir (const char *path_dir)Arguments#
path_dir
String that specifies EITHER the absolute working directory path to set OR a relative path that will be applied to the current working directory.
Returned Value#
0, if no error occurs.
-1, otherwise.
Notes / Warnings#
None.
fs_getcwd()#
Description#
Get the working directory for the current task.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
char *fs_getcwd (char *path_dir,
fs_size_t size)Arguments#
path_dir
String buffer that will receive the working directory path.
size
Size of string buffer.
Returned Value#
Pointer to working directory path, if no error occurs.
Pointer to NULL, otherwise.
Notes / Warnings#
None.
fs_opendir()#
Description#
Open a directory.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
FS_DIR *fs_opendir (const char *name_full)Arguments#
name_full
Name of the directory.
Returned Value#
Pointer to a directory, if NO errors.
Pointer to NULL, otherwise.
Notes / Warnings#
None.
fs_closedir()#
Description#
Close and free a directory.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_closedir (FS_DIR *p_dir)Arguments#
p_dir
Pointer to a directory.
Returned Value#
0, if directory is successfully closed.
-1, if any error was encountered.
Notes / Warnings#
After a directory is closed, the application MUST cease from accessing its directory pointer. This could cause file system corruption, since this handle may be re-used for a different directory.
fs_readdir_r()#
Description#
Read a directory entry from a directory.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_readdir_r (FS_DIR *p_dir,
struct fs_dirent *p_dir_entry,
struct fs_dirent **pp_result)Arguments#
p_dir
Pointer to a directory.
p_dir_entry
Pointer to variable that will receive directory entry information.
pp_result
Pointer to variable that will receive :
(a) ... 'p_dir_entry' if NO error occurs AND directory does not encounter EOF.
(b) ... pointer to NULL if an error occurs OR directory encounters EOF.
Returned Value#
1, if an error occurs.
0, if no error occurs.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section '
readdir(): DESCRIPTION' states that :(a) "The '
readdir()' function shall not return directory entries containing empty names. If entries for dot or dot-dot exist, one entry shall be returned for dot and one entry shall be returned for dot-dot; otherwise, they shall not be returned."(b) "If a file is removed from or added to the directory after the most recent call to 'opendir()' or '
rewinddir()', whether a subsequent call to 'readdir()' returns an entry for that file is unspecified."IEEE Std 1003.1, 2004 Edition, Section 'readdir() : RETURN VALUE' states that "[i]f successful, the '
readdir_r()' function shall return zero; otherwise, an error shall be returned to indicate the error".The directory entry information has the following fields:
struct fs_dirent {
fs_ino_t d_ino; /* File serial number. */
char d_name[256]; /* Buffer receiving directory entry name. */
};fs_mkdir()#
Description#
Create a directory.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_mkdir (const char *name_full)Arguments#
name_full
Name of the directory.
Returned Value#
-1, if an error occurs.
0, if no error occurs.
Notes / Warnings#
None.
fs_remove()#
Description#
Delete a file or directory.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_remove (const char *name_full)Arguments#
name_full
Name of the entry.
Returned Value#
0, if the entry is removed.
-1, if the entry is NOT removed.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section '
remove(): DESCRIPTION' states that :(a) "If '
path' does not name a directory, 'remove(path)' shall be equivalent to 'unlink(path)'."(b) "If path names a directory,
remove(path)shall be equivalent tormdir(path)."See '
fs_rmdir()Note(s)'.
fs_rename()#
Description#
Rename a file or directory.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_rename (const char *name_full_old,
const char *name_full_new)Arguments#
name_full_old
Old path of the entry.
name_full_new
New path of the entry.
Returned Value#
0, if the entry is renamed.
-1, if the entry is NOT renamed.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section 'rename() : DESCRIPTION' states that :
(a) "If the 'old' argument and the 'new' argument resolve to the same existing file, 'rename()' shall return successfully and perform no other action."
(b) "If the 'old' argument points to the pathname of a file that is not a directory, the 'new' argument shall not point to the pathname of a directory. If the link named by the 'new' argument exists, it shall be removed and 'old' renamed to 'new'."
(c) "If the 'old' argument points to the pathname of a directory, the 'new' argument shall not point to the pathname of a file that is not a directory. If the directory named by the 'new' argument exists, it shall be removed and 'old' renamed to 'new'."
"If 'new' names an existing directory, it shall be required to be an empty directory."
(d) "The 'new' pathname shall not contain a path prefix that names 'old'."
IEEE Std 1003.1, 2004 Edition, Section '
rename(): RETURN VALUE' states that "[u]pon successful completion, 'rename()' shall return 0; otherwise, -1 shall be returned".
fs_rmdir()#
Description#
Delete a directory.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_rmdir (const char *name_full)Arguments#
name_full
Name of the directory.
Returned Value#
0, if the directory is removed.
-1, if the directory is NOT removed.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section '
rmdir(): DESCRIPTION' states that :(a) "The '
rmdir()' function shall remove a directory whose name is given by path. The directory shall be removed only if it is an empty directory."(b) "If the directory is the root directory or the current working directory of any process, it is unspecified whether the function succeeds, or whether it shall fail"
IEEE Std 1003.1, 2004 Edition, Section '
rmdir(): RETURN VALUE' states that "[u]pon successful completion, the function 'rmdir()' shall return 0. Otherwise, -1 shall be returned".The root directory CANNOT be removed.
fs_stat()#
Description#
Get information about a file or directory.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_stat (const char *name_full,
struct fs_stat *p_info)Arguments#
name_full
Name of the entry.
p_info
Pointer to structure that will receive the entry information.
Returned Value#
0, if the function succeeds.
-1, otherwise.
Notes / Warnings#
The entry information structure has the following fields:
struct fs_stat {
fs_dev_t st_dev; /* Device ID of device containing file. */
fs_ino_t st_ino; /* File serial number. */
fs_mode_t st_mode; /* Mode of file. */
fs_nlink_t st_nlink; /* Number of hard links to the file. */
fs_uid_t st_uid; /* User ID of file. */
fs_gid_t st_gid; /* Group ID of file. */
fs_off_t st_size; /* File size in bytes. */
fs_time_t st_atime; /* Time of last access. */
fs_time_t st_mtime; /* Time of last data modification. */
fs_time_t st_ctime; /* Time of last status change. */
fs_blksize_t st_blksize; /* Preferred I/O block size for file. */
fs_blkcnt_t st_blocks; /* Number of blocks allocated for file. */
};fs_fopen()#
Description#
Open a file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
FS_FILE *fs_fopen (const char *name_full,
const char *str_mode)Arguments#
name_full
Name of the file.
str_mode
Access mode of the file (see Note #1a).
Returned Value#
Pointer to a file, if NO errors.
Pointer to NULL, otherwise.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section 'fopen() : DESCRIPTION' states that :
(a) "If ['str_mode'] is one of the following, the file is open in the indicated mode." :
"r or rb"
Open file for reading
"w or wb"
Truncate to zero length or create file for writing
"a or ab"
Append; open and create file for writing at end-of-file
"r+ or rb+ or r+b"
Open file for update (reading and writing)
"w+ or wb+ or w+b"
Truncate to zero length or create file for update
"a+ or ab+ or a+b"
Append; open or create for update, writing at end-of-file
(b) "The character 'b' shall have no effect"
(c) "Opening a file with read mode ... shall fail if the file does not exist or cannot be read"
(d) "Opening a file with append mode ... shall cause all subsequent writes to the file to be forced to the then current end-of-file"
(e) "When a file is opened with update mode ... both input and output may be performed.... However, the application shall ensure that output is not directly followed by input without an intervening call to '
fflush()' or to a file positioning function ('fseek()', 'fsetpos()', or 'rewind()'), and input is not directly followed by output without an intervening call to a file positioning function, unless the input operation encounters end-of-file."IEEE Std 1003.1, 2004 Edition, Section '
fopen(): RETURN VALUE' states that "[u]pon successful completion 'fopen()' shall return a pointer to the object controlling the stream. Otherwise a null pointer shall be returned'.
fs_fclose()#
Description#
Close and free a file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_fclose (FS_FILE *p_file)Arguments#
p_file
Pointer to a file.
Returned Value#
0, if the file was successfully closed.
EOF, otherwise.
Notes / Warnings#
After a file is closed, the application MUST cease from accessing its file pointer. This could cause file system corruption, since this handle may be re-used for a different file.
(a) If the most recent operation is output (write), all unwritten data is written to the file.
(b) Any buffer assigned with fs_setbuf() or fs_setvbuf() shall no longer be accessed by the file system and may be re-used by the application.
fs_fread()#
Description#
Read from a file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
fs_size_t fs_fread (void *p_dest,
fs_size_t size,
fs_size_t nitems,
FS_FILE *p_file)Arguments#
p_dest
Pointer to destination buffer.
size
Size of each item to read.
nitems
Number of items to read.
p_file
Pointer to a file.
Returned Value#
Number of items read.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section 'fread() : DESCRIPTION' states that :
(a) "The '
fread()' function shall read into the array pointed to by 'ptr' up to 'nitems' elements whose size is specified by 'size' in bytes"(b) "The file position indicator for the stream ... shall be advanced by the number of bytes successfully read"
IEEE Std 1003.1, 2004 Edition, Section '
fread(): RETURN VALUE' states that "[u]pon completion, 'fread()' shall return the number of elements which is less than 'nitems' only if a read error or end-of-file is encountered".See '
fs_fopen()Note #1e'.The file MUST have been opened in read or update (read/write) mode.
If an error occurs while reading from the file, a value less than '
nitems' will be returned. To determine whether the premature return was caused by reaching the end-of-file, the 'fs_feof()' function should be used :
rtn = fs_fread(pbuf, 1, 1000, pfile);
if (rtn \< 1000) {
eof = fs_feof();
if (eof != 0) {
// File has reached EOF
} else {
// Error has occurred
}
}fs_fwrite()#
Description#
Write to a file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
fs_size_t fs_fwrite (const void *p_src,
fs_size_t size,
fs_size_t nitems,
FS_FILE *p_file)Arguments#
p_src
Pointer to source buffer.
size
Size of each item to write.
nitems
Number of items to write.
p_file
Pointer to a file.
Returned Value#
Number of items written.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section '
fwrite(): DESCRIPTION' states that :(a) "The '
fwrite()' function shall write, from the array pointed to by 'ptr', up to 'nitems' elements whose size is specified by 'size', to the stream pointed to by 'stream'"(b) "The file position indicator for the stream ... shall be advanced by the number of bytes successfully written"
IEEE Std 1003.1, 2004 Edition, Section '
fwrite(): RETURN VALUE' states that "'fwrite()' shall return the number of elements successfully written, which may be less than 'nitems' if a write error is encountered".See '
fs_fopen()Notes #1d & #1e'.The file MUST have been opened in write or update (read/write) mode.
fs_ftruncate()#
Description#
Truncate a file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_ftruncate (int file_desc,
fs_off_t size)Arguments#
p_file
Pointer to a file.
size
Length of file after truncation.
Returned Value#
0, if the function succeeds.
-1, otherwise.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section 'ftruncate() : DESCRIPTION' states that :
(a) "If 'fildes' is not a valid file descriptor open for writing, the 'ftruncate()' function shall fail."
(b) "[The] '
ftruncate()' function shall cause the size of the file to be truncated to 'length'.""If the size of the file previously exceeded length, the extra data shall no longer be available to reads on the file."
"If the file previously was smaller than this size, '
ftruncate' shall either increase the size of the file or fail." This implementation increases the size of the file.
IEEE Std 1003.1, 2004 Edition, Section '
ftruncate(): DESCRIPTION' states that [u]pon successful completion, 'ftruncate()' shall return 0; otherwise -1 shall be returned and 'errno' set to indicate the error".If the file position indicator before the call to '
fs_ftruncate()' lay in the extra data destroyed by the function, then the file position will be set to the end-of-file.
fs_feof()#
Description#
Test EOF (End Of File) indicator on a file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_feof (FS_FILE *p_file)Arguments#
p_file
Pointer to a file.
Returned Value#
0, if EOF indicator is NOT set or if an error occurred.
Non-zero value, if EOF indicator is set.
Notes / Warnings#
The return value from this function should ALWAYS be tested against 0 :
rtn = fs_feof(pfile);
if (rtn == 0) {
// EOF indicator is NOT set
} else {
// EOF indicator is set
}If the end-of-file indicator is set, that is
fs_feof()returns a non-zero value,fs_clearerr()can be used to clear that indicator.
fs_ferror()#
Description#
Test error indicator on a file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_ferror (FS_FILE *p_file)Arguments#
p_file
Pointer to a file.
Returned Value#
0, if error indicator is NOT set or if an error occurred.
Non-zero value, if error indicator is set.
Notes / Warnings#
The return value from this function should ALWAYS be tested against 0 :
rtn = fs_ferror(pfile);
if (rtn == 0) {
// Error indicator is NOT set
} else {
// Error indicator is set
}If the error indicator is set, that is fs_ferror() returns a non-zero value, fs_clearerr() can be used to clear that indicator.
fs_clearerr()#
Description#
Clear EOF (End Of File) and error indicators on a file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
void fs_clearerr (FS_FILE *p_file)Arguments#
p_file
Pointer to a file.
Returned Value#
none.
Notes / Warnings#
None.
fs_fgetpos()#
Description#
Get file position indicator.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_fgetpos (FS_FILE *p_file,
fs_fpos_t *p_pos)Arguments#
p_file
Pointer to a file.
p_pos
Pointer to variable that will receive the file position indicator.
Returned Value#
0, if no error occurs.
Non-zero value, otherwise.
Notes / Warnings#
The return value should be tested against 0 :
rtn = fs_fgetpos(pfile, &pos);
if (rtn == 0) {
// No error occurred.
} else {
// Handle error.
}The value placed in '
p_pos' should be passed tofs_fsetpos()to reposition the file to its position at the time when this function was called.
fs_fsetpos()#
Description#
Set file position indicator.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_fsetpos ( FS_FILE *p_file,
const fs_fpos_t *p_pos)Arguments#
p_file
Pointer to a file.
p_pos
Pointer to variable holding the file position.
Returned Value#
0, if the function succeeds.
Non-zero value, otherwise.
Notes / Warnings#
The return value should be tested against 0 :
rtn = fs_fsetpos(pfile, &pos);
if (rtn == 0) {
// No error occurred.
} else {
// Handle error.
}IEEE Std 1003.1, 2004 Edition, Section '
fsetpos(): DESCRIPTION' states that :(a) "If a read or write error occurs, the error indicator for the stream is set"
(b) "The '
fsetpos()' function shall set the file position and state indicators for the stream pointed to by stream according to the value of the object pointed to by 'pos', which the application shall ensure is a value obtained from an earlier call to 'fgetpos()' on the same stream."IEEE Std 1003.1, 2004 Edition, Section '
fsetpos(): RETURN VALUE' states that "[t]he 'fsetpos()' function shall return 0 if it succeeds; otherwise, it shall return a non-zero value".No attempt is made to verify that the value stored in '
p_pos' was returned from 'fs_fgetpos()'.See also '
fs_fseek()Note #1d'.
fs_fseek()#
Description#
Set file position indicator.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_fseek (FS_FILE *p_file,
long int offset,
int origin)Arguments#
p_file
Pointer to a file.
offset
Offset from file position specified by 'origin'.
origin
Reference position for offset :
SEEK_SET Offset is from the beginning of the file.
SEEK_CUR Offset is from current file position.
SEEK_END Offset is from the end of the file.
Returned Value#
0, if the function succeeds.
-1, otherwise.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section 'fread() : DESCRIPTION' states that :
(a) "If a read or write error occurs, the error indicator for the stream shall be set"
(b) "The new position measured in bytes from the beginning of the file, shall be obtained by adding 'offset' to the position specified by 'whence'. The specified point is ..."
"... the beginning of the file for
SEEK_SET""... the current value of the file-position indicator for
SEEK_CUR""... end-of-file for
SEEK_END"
(c) "A successful call to '
fseek()' shall clear the end-of-file indicator"(d) "The '
fseek()' function shall allow the file-position indicator to be set beyond the end of existing data in the file. If data is later written at this point, subsequent reads of data in the gap shall return bytes with the value 0 until data is actually written into the gap."IEEE Std 1003.1, 2004 Edition, Section '
fread(): RETURN VALUE' states that "[t]he 'fseek()' and 'fseeko()' functions shall return 0 if they succeeds. Otherwise, they shall return -1".If the file position indicator is set beyond the file's current data, the file MUST be opened in write or read/write mode.
fs_ftell()#
Description#
Get file position indicator.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
long int fs_ftell (FS_FILE *p_file)Arguments#
p_file
Pointer to a file.
Returned Value#
The current file position, if the function succeeds.
-1, otherwise.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section 'ftell() : RETURN VALUE' states that :
(a) "Upon successful completion, '
ftell()' and 'ftello()' shall return the current value of the file-position indicator for the stream measured in bytes from the beginning of the file."(b) "Otherwise, '
ftell()' and 'ftello()' shall return -1, cast to 'long' and 'off_t' respectively, and set errno to indicate the error."
fs_rewind()#
Description#
Reset file position indicator of a file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
void fs_rewind (FS_FILE *p_file)Arguments#
p_file
Pointer to a file.
Returned Value#
none.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section '
rewind(): DESCRIPTION' states that :
"[T]he call 'rewind(stream)' shall be equivalent to '(void)fseek(stream, 0L, SEEK_SET)' except that 'rewind()' shall also clear the error indicator."
fs_fileno()#
Description#
Get file descriptor integer associated to file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_fileno (FS_FILE *p_file)Arguments#
p_file
Pointer to a file.
Returned Value#
File descriptor integer, if NO errors.
-1, otherwise.
Notes / Warnings#
None.
fs_fstat()#
Description#
Get information about a file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_fstat (int file_desc,
struct fs_stat *p_info)Arguments#
p_file
Pointer to a file.
p_info
Pointer to structure that will receive the file information.
Returned Value#
0, if the function succeeds.
-1, otherwise.
Notes / Warnings#
The file information structure has the following fields:
struct fs_stat {
fs_dev_t st_dev; /* Device ID of device containing file. */
fs_ino_t st_ino; /* File serial number. */
fs_mode_t st_mode; /* Mode of file. */
fs_nlink_t st_nlink; /* Number of hard links to the file. */
fs_uid_t st_uid; /* User ID of file. */
fs_gid_t st_gid; /* Group ID of file. */
fs_off_t st_size; /* File size in bytes. */
fs_time_t st_atime; /* Time of last access. */
fs_time_t st_mtime; /* Time of last data modification. */
fs_time_t st_ctime; /* Time of last status change. */
fs_blksize_t st_blksize; /* Preferred I/O block size for file. */
fs_blkcnt_t st_blocks; /* Number of blocks allocated for file. */
};fs_flockfile()#
Description#
Acquire task ownership of a file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
void fs_flockfile (FS_FILE *p_file)Arguments#
p_file
Pointer to a file.
Returned Value#
none.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section '
flockfile(),ftrylockfile(),funlockfile(): DESCRIPTION' states that :(a) "The '
flockfile()' function shall acquire thread ownership of a(FILE *)object."(b) "The functions shall behave as if there is a lock count associated with each
(FILE *)object.""The
(FILE *)object is unlocked when the count is zero.""When the count is positive, a single thread owns the
(FILE *)object.""When the '
flockfile()' function is called, if the count is zero or if the count is positive and the caller owns the(FILE *), the count shall be incremented. Otherwise, the calling thread shall be suspended, waiting for the count to return to zero.""Each call to '
funlockfile()' shall decrement the count.""This allows matching calls to '
flockfile()' (or successful calls to 'ftrylockfile()') and 'funlockfile()' to be nested."
fs_ftrylockfile()#
Description#
Acquire task ownership of a file (if available).
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_ftrylockfile (FS_FILE *p_file)Arguments#
p_file
Pointer to a file.
Returned Value#
0, if no error occurs and the file lock is acquired.
Non-zero value, otherwise.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section '
flockfile(),ftrylockfile(),funlockfile(): DESCRIPTION' states that :(a) See '
fs_flockfile()Note(s)'.(b) "The '
ftrylockfile()function shall acquire for a thread ownership of a(FILE *)object if the object is available; 'ftrylockfile()' is a non-blocking version of 'flockfile()'."IEEE Std 1003.1, 2004 Edition, Section '
flockfile(),ftrylockfile(),funlockfile(): RETURN VALUES' states that "[t]he 'ftrylockfile()' function shall return zero for success and non-zero to indicate that the lock cannot be acquired".
fs_funlockfile()#
Description#
Release task ownership of a file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
void fs_funlockfile (FS_FILE *p_file)Arguments#
p_file
Pointer to a file.
Returned Value#
none.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section '
flockfile(),ftrylockfile(),funlockfile(): DESCRIPTION' states that :(a) See '
fs_flockfile()Note(s)'.
fs_setbuf()#
Description#
Assign buffer to a file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
void fs_setbuf (FS_FILE *p_file,
char *p_buf)Arguments#
p_file
Pointer to a file.
p_buf
Pointer to buffer.
Returned Value#
none.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section '
setbuf(): DESCRIPTION' states that :
"Except that it returns no value, the function call: 'setbuf(stream, buf)' shall be equivalent to: 'setvbuf(stream, buf, _IOFBF, BUFSIZ)' if 'buf' is not a null pointer"
See '
fs_setvbuf()Note(s)'.
fs_setvbuf()#
Description#
Assign buffer to a file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_setvbuf (FS_FILE *p_file,
char *p_buf,
int mode,
fs_size_t size)Arguments#
p_file
Pointer to a file.
p_buf
Pointer to buffer.
mode
Buffer mode.
_IOFBFData buffered for reads & writes._IONBRData unbuffered for reads & writes.
size
Size of buffer, in octets.
Returned Value#
-1, if an error occurs.
0, if no error occurs.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section '
setvbuf(): DESCRIPTION' states that :(a) "The
setvbuf()function may be used after the stream pointed to by stream is associated with an open file but before any other operation (other than an unsuccessful call tosetvbuf()) is performed on the stream."(b) "The argument 'mode' determines how 'stream' will be buffered ... "
...
FS__IOFBF"causes input/output to be fully buffered"....
FS__IONBF"causes input/output to be unbuffered".No equivalent to '
_IOLBF' is supported.
(c) "If '
buf' is not a null pointer, the array it points to may be used instead of a buffer allocated by the 'setvbuf' function and the argument 'size' specifies the size of the array ...." This implementation REQUIRES that 'buf' not be a null pointer; the array 'buf' points to will always be used.(d) The function "returns zero on success, or nonzero if an invalid value is given for 'mode' or if the request cannot be honored".
'size' MUST be more than or equal to the size of one sector and will be rounded DOWN to the size of a number of full sectors.
Once a buffer is assigned to a file, a new buffer may not be assigned nor may the assigned buffer be removed. To change the buffer, the file should be closed & re-opened.
Upon power loss, any data stored in file buffers will be lost.
fs_fflush()#
Description#
Flush buffer contents to file.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
int fs_fflush (FS_FILE *p_file)Arguments#
p_file
Pointer to a file.
Returned Value#
0, if flushing succeeds.
EOF, otherwise.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section '
fflush(): DESCRIPTION' states that :(a) "If '
stream' points to an output stream or an update stream in which the most recent operation was not input, 'fflush()' shall cause any unwritten data for that stream to be written to the file."(b) "If 'stream' is a null pointer, the '
fflush' function performs this flushing action on all streams ...." #### Currently unimplemented.(c) "Upon successful completion,
fflush()shall return 0; otherwise, it shall set the error indicator for the stream, return EOF."IEEE Std 1003.1, 2004 Edition, Section '
fflush()' defines no behavior for an input stream or update stream in which the most recent operation was input.(a) In this implementation, if the most recent operation is input,
fs_fflush()clears all buffered input data.
fs_asctime_r()#
Description#
Convert date/time to string.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
char *fs_asctime_r (const struct fs_tm *p_time,
char *p_str_time)Arguments#
p_time
Pointer to date/time to format.
p_str_time
String buffer that will receive the date/time string (see Note #1).
Returned Value#
Pointer to date/time string, if NO errors.
Pointer to NULL, otherwise.
Notes / Warnings#
String buffer MUST be at least 26 characters long. Buffer overruns MUST be prevented by caller.
IEEE Std 1003.1, 2004 Edition, Section '
asctime(): DESCRIPTION' states that :(a) "The '
asctime()' function shall convert the broken-down time in the structure pointed to by 'timeptr' into a string in the form: Sun Sep 16 01:03:52 1973\n\0.
fs_ctime_r()#
Description#
Convert timestamp to string.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
char *fs_ctime_r (const fs_time_t *p_ts,
char *p_str_time)Arguments#
p_ts
Pointer to timestamp to format.
str_time
String buffer that will receive the timestamp string (see Note #1).
Returned Value#
Pointer to timestamp buffer, if NO errors.
Pointer to NULL, otherwise.
Notes / Warnings#
The timestamp buffer MUST be at least 26 characters long. buffer overruns MUST be prevented by caller.
IEEE Std 1003.1, 2004 Edition, Section '
ctime(): DESCRIPTION' states that :(a) '
ctime' "shall be equivalent to: 'asctime(localtime(clock))'".
fs_localtime_r()#
Description#
Convert timestamp to date/time.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
struct fs_tm *fs_localtime_r (const fs_time_t *p_ts,
struct fs_tm *p_time)Arguments#
p_ts
Pointer to timestamp to convert.
p_time
Pointer to variable that will receive the date/time.
Returned Value#
Pointer to date/time, if NO errors.
Pointer to NULL, otherwise.
Notes / Warnings#
IEEE Std 1003.1, 2004 Edition, Section '4.14 Seconds Since the Epoch()' states that
(a) "If the year is <1970 or the value is negative, the relationship is undefined. If the year is >=1970 and the value is non-negative, the value is related to coordinated universal time name according to the C-language expression, where
tm_sec,tm_min,tm_hour,tm_yday, andtm_yearare all integer types:tm_sec + tm_min*60 + tm_hour*3600 + tm_yday*86400 + (tm_year-70)*31536000 + ((tm_year-69)/4)*86400 - ((tm_year-1)/100)*86400 + ((tm_year+299)/400)*86400(b) "The relationship between the actual time of day and the current value for seconds since the Epoch is unspecified."
The expression for the time value can be rewritten :
time_val = tm_sec + 60 * (tm_min +
60 * (tm_hour +
24 * (tm_yday + ((tm_year-69)/4) - ((tm_year-1)/100) + ((tm_year+299)/400) +
365 * (tm_year - 70))))fs_mktime()#
Description#
Convert date/time to timestamp.
Files#
fs_core_posix.h/fs_core_posix.c
Prototype#
fs_time_t fs_mktime (struct fs_tm *p_time)Arguments#
p_time
Pointer to date/time to convert.
Returned Value#
Time value, if NO errors.
(
fs_time_t)-1, otherwise.
Notes / Warnings#
See '
fs_localtime_r()Note #1'.IEEE Std 1003.1, 2004 Edition, Section '
mktime(): DESCRIPTION' states that :(a) "The '
mktime()' function shall convert the broken-down time, expressed as local time, in the structure pointed to by 'timeptr', into a time since the Epoch"(b) "The original values of '
tm_wday' and 'tm_yday' components of the structure are ignored, and the original values of the other components are not restricted to the ranges described in<time.h>" (see also Note #3)(c) "Upon successful completion, the values of the '
tm_wday' and 'tm_yday' components of the structure shall be set appropriately, and the other components set to represent the specified time since the Epoch, but with their values forced to the ranges indicated in the<time.h>entry"Even though strict range checking is NOT performed, the broken-down date/time components are restricted to positive values, and the month value MUST be between 0 & 11 (otherwise, the day of year cannot be determined).