File

Contains file related os apis. More...

Classes

struct  _OS_FILE_UNIQUE_ID

Typedefs

typedef _OS_FILE_UNIQUE_ID OS_FILE_UNIQUE_ID
typedef UINT64 OS_PROCESS_WAITABLE_PROCESS

Enumerations

enum  OS_FILE_OPEN_TYPE {
  OS_FILE_OPEN_TYPE_READ = (1<<0),
  OS_FILE_OPEN_TYPE_WRITE = (1<<1),
  OS_FILE_OPEN_TYPE_EXECUTE = (1<<2),
  OS_FILE_OPEN_TYPE_APPEND = (1<<3),
  OS_FILE_OPEN_TYPE_TRUNCATE = (1<<4),
  OS_FILE_OPEN_TYPE_CREATE = (1<<5),
  OS_FILE_OPEN_TYPE_CREATE_EXCL = (1<<6),
  OS_FILE_OPEN_TYPE_DELETE = (1<<7),
  OS_FILE_OPEN_TYPE_CLOSE_ON_EXEC = (1<<8)
}
enum  OS_FILE_PERMISSION_TYPE {
  OS_FILE_PERMISSION_TYPE_READ = (1<<0),
  OS_FILE_PERMISSION_TYPE_WRITE = (1<<1),
  OS_FILE_PERMISSION_TYPE_EXECUTE = (1<<2)
}
enum  OS_FILE_SEEK_TYPE {
  OS_FILE_SEEK_SET = 0,
  OS_FILE_SEEK_CUR = (1<<0),
  OS_FILE_SEEK_END = (1<<1)
}
enum  OS_FILE_ATTRIBUTES {
  OS_FILE_ATTRIBUTES_NONE = 0,
  OS_FILE_ATTRIBUTES_EXIST = (1<<0),
  OS_FILE_ATTRIBUTES_REGULAR = (1<<1),
  OS_FILE_ATTRIBUTES_DIRECTORY = (1<<2),
  OS_FILE_ATTRIBUTES_SYMLINK = (1<<3)
}
enum  OS_PIPE_CREATE_FLAGS {
  OS_PIPE_CREATE_FLAGS_NONE = 0,
  OS_PIPE_CREATE_FLAGS_READ_SIDE_INHERITABLE = (1<<0),
  OS_PIPE_CREATE_FLAGS_WRITE_SIDE_INHERITABLE = (1<<1)
}

Functions

OS_RETURN_CODE OS_OpenFD (const CHAR *path, INT flags, INT mode, NATIVE_FD *fd)
OS_RETURN_CODE OS_WriteFD (NATIVE_FD fd, const VOID *buffer, USIZE *count)
OS_RETURN_CODE OS_ReadFD (NATIVE_FD fd, USIZE *count, VOID *buffer)
OS_RETURN_CODE OS_SeekFD (NATIVE_FD fd, INT whence, INT64 *offset)
OS_RETURN_CODE OS_CloseFD (NATIVE_FD fd)
OS_RETURN_CODE OS_DeleteFile (const CHAR *name)
OS_RETURN_CODE OS_FlushFD (NATIVE_FD fd)
OS_RETURN_CODE OS_GetFDAttributes (NATIVE_FD fd, OS_FILE_ATTRIBUTES *attr)
OS_RETURN_CODE OS_FilePermissionsFD (NATIVE_FD fd, OS_FILE_PERMISSION_TYPE *permissions)
OS_RETURN_CODE OS_FileSizeFD (NATIVE_FD fd, USIZE *size)
OS_RETURN_CODE OS_Cwd (CHAR *cwd, INT len)
OS_RETURN_CODE OS_Chdir (const CHAR *dir, CHAR *cwd, INT len)
OS_RETURN_CODE OS_OpenDirFD (const CHAR *name, NATIVE_FD *fd)
OS_RETURN_CODE OS_MkDir (const CHAR *name, INT mode)
OS_RETURN_CODE OS_DeleteDirectory (const CHAR *name)
OS_RETURN_CODE OS_IsConsoleFD (NATIVE_FD fd, INT *isConsole)
OS_RETURN_CODE OS_ReadDirectoryFD (NATIVE_FD fd, USIZE *count, VOID *buffer)
OS_RETURN_CODE OS_GetFDAccessMode (NATIVE_FD fd, OS_FILE_OPEN_TYPE *mode)
OS_RETURN_CODE OS_ReadLink (const CHAR *path, CHAR *buf, USIZE *size)
OS_RETURN_CODE OS_GetFileAttributes (const CHAR *path, OS_FILE_ATTRIBUTES *attr)
OS_RETURN_CODE OS_RenameFile (const CHAR *oldPath, const CHAR *newPath)
OS_RETURN_CODE OS_FileUniqueID (NATIVE_FD fd, OS_FILE_UNIQUE_ID *uniqueId)
OS_RETURN_CODE OS_DuplicateFD (NATIVE_FD fd, BOOL_T dupCloseOnExec, NATIVE_FD *outFd)
void OS_ReportFileOpen (NATIVE_FD fd)
void OS_ReportFileClose (NATIVE_FD fd)
NATIVE_FD OS_GetLowestFileDescriptorToUse ()
void OS_RelocateAndReportFileOpen (NATIVE_FD *fd)
BOOL_T OS_WasFileReportedOpen (NATIVE_FD fd)

Detailed Description


Typedef Documentation

typedef struct _OS_FILE_UNIQUE_ID OS_FILE_UNIQUE_ID
 

Machine unique ID for file

typedef UINT64 OS_PROCESS_WAITABLE_PROCESS
 

Opaque object that represents a process that we can wait for its termination


Enumeration Type Documentation

enum OS_FILE_ATTRIBUTES
 

File permission modes

enum OS_FILE_OPEN_TYPE
 

File open modes

enum OS_FILE_PERMISSION_TYPE
 

File permission modes

enum OS_FILE_SEEK_TYPE
 

File seek modes

Enumerator:
OS_FILE_SEEK_SET  Offset is set to the given offset bytes.
OS_FILE_SEEK_CUR  Offset is set to its current location plus offset bytes.
OS_FILE_SEEK_END  Offset is set to the size of the file plus offset bytes.

enum OS_PIPE_CREATE_FLAGS
 

Pipes creation flags


Function Documentation

OS_RETURN_CODE OS_Chdir const CHAR *  dir,
CHAR *  cwd,
INT  len
 

Sets a new current directory. Optionally records the previous directory.

Parameters:
[in] dir The directory to move to.
[out] cwd Buffer to receive the CWD.
[in] len Max buffer length for cwd.
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_QUERY_FAILED If current directory capture failed
OS_RETURN_CODE_FILE_OPEN_FAILED If the operation failed
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_CloseFD NATIVE_FD  fd  ) 
 

Closes fd and removes references to it from the process.

Parameters:
[in] fd File descriptor
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_CLOSE_FAILED If the operation failed
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_Cwd CHAR *  cwd,
INT  len
 

Retrieves size in bytes of fd.

Parameters:
[out] cwd Buffer to receive the CWD.
[in] len Max buffer length.
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_QUERY_FAILED If the operation failed
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_DeleteDirectory const CHAR *  name  ) 
 

Deletes a directory.

Parameters:
[in] name Directory file name to delete.
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded.
OS_RETURN_CODE_FILE_DELETE_FAILED If the operation failed.
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_DeleteFile const CHAR *  name  ) 
 

Delete a file by name

Parameters:
[in] name File path.
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_DELETE_FAILED If the operation failed
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_DuplicateFD NATIVE_FD  fd,
BOOL_T  dupCloseOnExec,
NATIVE_FD outFd
 

Creates a copy of a file descriptor using the lowest available free file descriptor. This function considers the value returned from OS_GetLowestFileDescriptorToUse() when duplicating the descriptor.

Parameters:
[in] fd File descriptor to duplicate an ID.
[in] dupCloseOnExec TRUE to duplicate the close-on-exec property of the descriptor, FALSE otherwise.
[out] outFd Result duplicated file descriptor.
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_OPERATION_FAILED If the operation failed
Availability:
O/S: Linux & OS X*
CPU: All

OS_RETURN_CODE OS_FilePermissionsFD NATIVE_FD  fd,
OS_FILE_PERMISSION_TYPE permissions
 

Retrieve the current permissions for the specified file.

Parameters:
[in] fd File descriptor
[out] permissions or'ed OS_FILE_PERMISSION_TYPE.
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_QUERY_FAILED If the operation failed
Remarks:
On Unix, will provide the user (not group/other) permissions.
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_FileSizeFD NATIVE_FD  fd,
USIZE *  size
 

Retrieves size in bytes of fd.

Parameters:
[in] fd File descriptor
[out] size Number of bytes.
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_QUERY_FAILED If the operation failed
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_FileUniqueID NATIVE_FD  fd,
OS_FILE_UNIQUE_ID uniqueId
 

Get unique ID for an opened file, identified by a file descriptor. Two opened file descriptors for the same physical file are guaranteed to have the same unique ID.

Parameters:
[in] fd File descriptor to calculate an ID.
[out] uniqueId The calculate unique ID (opaque binary data)
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_QUERY_FAILED If the operation failed
Availability:
O/S: Linux
CPU: All

OS_RETURN_CODE OS_FlushFD NATIVE_FD  fd  ) 
 

Flush the object referenced by the descriptor fd.

Parameters:
[in] fd File descriptor
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_FLUSH_FAILED If the operation failed
Availability:
O/S: Windows
CPU: All

OS_RETURN_CODE OS_GetFDAccessMode NATIVE_FD  fd,
OS_FILE_OPEN_TYPE mode
 

Get the permissions type requested when fd was opened. This is useful to check whether we can read or write fd.

Parameters:
[in] fd File descriptor to check.
[out] mode The permissions of the file descriptor.
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded.
OS_RETURN_CODE_FILE_QUERY_FAILED If the operation failed.
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_GetFDAttributes NATIVE_FD  fd,
OS_FILE_ATTRIBUTES attr
 

Query fd's file attributes

Parameters:
[in] fd File descriptor
[out] attr File attributes
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_QUERY_FAILED If the operation failed
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_GetFileAttributes const CHAR *  path,
OS_FILE_ATTRIBUTES attr
 

Query file attributes of the file denoted by path

Parameters:
[in] path Path to file
[out] attr File attributes
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_QUERY_FAILED If the operation failed
Availability:
O/S: Windows, Linux & OS X*
CPU: All

NATIVE_FD OS_GetLowestFileDescriptorToUse  ) 
 

Getter function to retrieve the lowest value of file descriptor that OS-APIs should use. OS-APIs will attempt to only use file descriptors which are larger or equal to the value that this function returns.

This function is implemented as a weak reference symbol so libraries linked with OS-APIs may provide their own implementation of this function and return a different value.

Return values:
Lowest file descriptor to use.
Availability:
O/S: Linux & OS X*
CPU: All

OS_RETURN_CODE OS_IsConsoleFD NATIVE_FD  fd,
INT *  isConsole
 

Check whether a file descriptor is the application's console. A file descriptor is the application's console if: 1. The file of the underlying descriptor is a terminal device. 2. The terminal device is the tty master (or console) of the current application.

The practical implication of a console file descriptor is that every write operation to it needs to be flushed right away because the user on the other side expects to see output immediately.

Parameters:
[in] fd File descriptor to check.
[out] isConsole non-zero if 'fd' is the application's console. Zero otherwise.
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded.
OS_RETURN_CODE_FILE_QUERY_FAILED If the operation failed.
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_MkDir const CHAR *  name,
INT  mode
 

Creates a directory.

Parameters:
[in] name Directory file name to create.
[in] mode File mode to create the directory.
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded.
OS_RETURN_CODE_FILE_EXIST Directory exists.
OS_RETURN_CODE_FILE_OPEN_FAILED If the operation failed.
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_OpenDirFD const CHAR *  name,
NATIVE_FD fd
 

Opens a directory for browsing.

Parameters:
[in] name Directory file name to open.
[out] fd Pointer to returned file descriptor.
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_OPEN_FAILED If the operation failed
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_OpenFD const CHAR *  path,
INT  flags,
INT  mode,
NATIVE_FD fd
 

The file name specified by path is opened for reading and/or writing, as specified by the argument flags.

Parameters:
[in] path File path.
[in] flags or'ed OS_FILE_OPEN_TYPE. If mode OS_FILE_OPEN_TYPE_CREATE
was given, the file is created with mode.
[in] mode If a new file will be created as a result of this operation, this is the mode of this newly created file. This argument contains values from OS_FILE_PERMISSION_TYPE combined with bitwise OR.
[out] fd Returned file descriptor
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_OPEN_FAILED If the operation Failed
Returns:
fd - Assigned with the file descriptor
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_ReadDirectoryFD NATIVE_FD  fd,
USIZE *  count,
VOID *  buffer
 

Attempts to read count bytes of data from the directory referenced by the descriptor fd to the buffer pointed to by buffer. A console file descriptor usually needs to be flushed after every read/write operation.

Parameters:
[in] fd File descriptor
[in,out] count Bytes to read/Bytes read
[out] buffer Output buffer
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_READ_FAILED If the operation failed
Returns:
count - Assigned with the number of bytes successfully read
buffer - Contains count bytes that were read from fd
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_ReadFD NATIVE_FD  fd,
USIZE *  count,
VOID *  buffer
 

Attempts to read count bytes of data from the object referenced by the descriptor fd to the buffer pointed to by buffer.

Parameters:
[in] fd File descriptor
[in,out] count Bytes to read
[out] buffer Output buffer
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_READ_FAILED If the operation failed
Returns:
size Assigned with the number of bytes successfully read
buffer Contains count bytes that were read from fd
Availability:
O/S: Windows, Linux & OS X*
CPU: All

OS_RETURN_CODE OS_ReadLink const CHAR *  path,
CHAR *  buf,
USIZE *  size
 

Reads the symbolic link pointed by path. Returns the path that the symlink points to.

Parameters:
[in] path Path to the symbolic link to read.
[out] buf The path where the symlink points to.
[in,out] size The number of bytes in buf, returns the number of bytes filled inside buf.
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded.
OS_RETURN_CODE_FILE_QUERY_FAILED If the operation failed.
Availability:
O/S: Linux & OS X*
CPU: All

void OS_RelocateAndReportFileOpen NATIVE_FD fd  ) 
 

Relocate the file descriptor to the range permitted according to OS_GetLowestFileDescriptorToUse(), then record a file descriptor as opened by OS-APIs. Later, we allow to query whether a certain file descriptor was opened by OS-APIs or not.

Parameters:
[in,out] fd File descriptor to relocate and record.
Availability:
O/S: Linux & OS X*
CPU: All

OS_RETURN_CODE OS_RenameFile const CHAR *  oldPath,
const CHAR *  newPath
 

Renamed the file oldPath to newPath

Parameters:
[in] oldPath Filename to rename
[in] newPath New filename to rename to
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_OPERATION_FAILED If the operation failed
Availability:
O/S: Windows, Linux & OS X*
CPU: All

void OS_ReportFileClose NATIVE_FD  fd  ) 
 

Record that a file descriptor opened by OS-APIs is not longer valid, and it is closed. Later, we allow to query whether a certain file descriptor was opened by OS-APIs or not.

Parameters:
[in] fd File descriptor to record.
Availability:
O/S: Linux & OS X*
CPU: All

void OS_ReportFileOpen NATIVE_FD  fd  ) 
 

Record a file descriptor as opened by OS-APIs. Later, we allow to query whether a certain file descriptor was opened by OS-APIs or not.

Parameters:
[in] fd File descriptor to record.
Availability:
O/S: Linux & OS X*
CPU: All

OS_RETURN_CODE OS_SeekFD NATIVE_FD  fd,
INT  whence,
INT64 *  offset
 

Reposition the offset of the file descriptor fd to the an offset in, the file denoted by offset. The offset is measured with relation to a starting point determined by the directive whence.

Parameters:
[in] fd File descriptor
[in] whence OS_FILE_SEEK_TYPE
[in,out] offset Bytes to move
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_SEEK_FAILED If the operation failed
Returns:
offset - Assigned with the number of bytes successfully read
Availability:
O/S: Windows, Linux & OS X*
CPU: All

BOOL_T OS_WasFileReportedOpen NATIVE_FD  fd  ) 
 

Queries whether a certain file descriptor was opened by OS-APIs or not.

Parameters:
[in] fd File descriptor to query.
Availability:
O/S: Linux & OS X*
CPU: All

OS_RETURN_CODE OS_WriteFD NATIVE_FD  fd,
const VOID *  buffer,
USIZE *  count
 

Attempts to write count bytes of data to the object referenced by the descriptor fd from the buffer pointed to by buffer.

Parameters:
[in] fd File descriptor
[in] buffer Data buffer
[in,out] count Bytes to write
Return values:
OS_RETURN_CODE_NO_ERROR If the operation succeeded
OS_RETURN_CODE_FILE_WRITE_FAILED If the operation failed
Returns:
size Assigned with the number of bytes successfully written
Availability:
O/S: Windows, Linux & OS X*
CPU: All


Generated on Thu Feb 2 21:59:15 2017 for PinCRT by  doxygen 1.4.6