PinCRT
Classes | Typedefs | Enumerations | Functions
File

Contains file related os apis.

Classes

struct  _OS_FILE_UNIQUE_ID

Typedefs

typedef struct _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)
OS_RETURN_CODE OS_Ftruncate (NATIVE_FD fd, INT64 length)
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)

Typedef Documentation

Machine unique ID for file

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


Enumeration Type Documentation

File permission modes

File open modes

File permission modes

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.

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]dirThe directory to move to.
[out]cwdBuffer to receive the CWD.
[in]lenMax buffer length for cwd.
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_QUERY_FAILEDIf current directory capture failed
OS_RETURN_CODE_FILE_OPEN_FAILEDIf the operation failed
Availability:
O/S: Windows, Linux & macOS*
CPU: All
OS_RETURN_CODE OS_CloseFD ( NATIVE_FD  fd)

Closes fd and removes references to it from the process.

Parameters:
[in]fdFile descriptor
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_CLOSE_FAILEDIf the operation failed
Availability:
O/S: Windows, Linux & macOS*
CPU: All
OS_RETURN_CODE OS_Cwd ( CHAR *  cwd,
INT  len 
)

Retrieves size in bytes of fd.

Parameters:
[out]cwdBuffer to receive the CWD.
[in]lenMax buffer length.
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_QUERY_FAILEDIf the operation failed
Availability:
O/S: Windows, Linux & macOS*
CPU: All
OS_RETURN_CODE OS_DeleteDirectory ( const CHAR *  name)

Deletes a directory.

Parameters:
[in]nameDirectory file name to delete.
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded.
OS_RETURN_CODE_FILE_DELETE_FAILEDIf the operation failed.
Availability:
O/S: Windows, Linux & macOS*
CPU: All
OS_RETURN_CODE OS_DeleteFile ( const CHAR *  name)

Delete a file by name

Parameters:
[in]nameFile path.
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_DELETE_FAILEDIf the operation failed
Availability:
O/S: Windows, Linux & macOS*
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]fdFile descriptor to duplicate an ID.
[in]dupCloseOnExecTRUE to duplicate the close-on-exec property of the descriptor, FALSE otherwise.
[out]outFdResult duplicated file descriptor.
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_OPERATION_FAILEDIf the operation failed
Availability:
O/S: Linux & macOS*
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]fdFile descriptor
[out]permissionsor'ed OS_FILE_PERMISSION_TYPE.
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_QUERY_FAILEDIf the operation failed
Remarks:
On Unix, will provide the user (not group/other) permissions.
Availability:
O/S: Windows, Linux & macOS*
CPU: All
OS_RETURN_CODE OS_FileSizeFD ( NATIVE_FD  fd,
USIZE *  size 
)

Retrieves size in bytes of fd.

Parameters:
[in]fdFile descriptor
[out]sizeNumber of bytes.
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_QUERY_FAILEDIf the operation failed
Availability:
O/S: Windows, Linux & macOS*
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]fdFile descriptor to calculate an ID.
[out]uniqueIdThe calculate unique ID (opaque binary data)
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_QUERY_FAILEDIf 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]fdFile descriptor
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_FLUSH_FAILEDIf the operation failed
Availability:
O/S: Windows
CPU: All
OS_RETURN_CODE OS_Ftruncate ( NATIVE_FD  fd,
INT64  length 
)

Truncates a file referenced by fd to a size of length bytes. If the original file size is bigger than length, the extra data is lost. If the original file size is smaller than length,the file extended.

Parameters:
[in]fdFile descriptor to change his size.
[in]lengthFile new length.
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_OPERATION_FAILEDIf the operation failed
Availability:
O/S: Windows & Linux & macOS*
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]fdFile descriptor to check.
[out]modeThe permissions of the file descriptor.
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded.
OS_RETURN_CODE_FILE_QUERY_FAILEDIf the operation failed.
Availability:
O/S: Windows, Linux & macOS*
CPU: All
OS_RETURN_CODE OS_GetFDAttributes ( NATIVE_FD  fd,
OS_FILE_ATTRIBUTES attr 
)

Query fd's file attributes

Parameters:
[in]fdFile descriptor
[out]attrFile attributes
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_QUERY_FAILEDIf the operation failed
Availability:
O/S: Windows, Linux & macOS*
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]pathPath to file
[out]attrFile attributes
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_QUERY_FAILEDIf the operation failed
Availability:
O/S: Windows, Linux & macOS*
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:
Lowestfile descriptor to use.
Availability:
O/S: Linux & macOS*
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]fdFile descriptor to check.
[out]isConsolenon-zero if 'fd' is the application's console. Zero otherwise.
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded.
OS_RETURN_CODE_FILE_QUERY_FAILEDIf the operation failed.
Availability:
O/S: Windows, Linux & macOS*
CPU: All
OS_RETURN_CODE OS_MkDir ( const CHAR *  name,
INT  mode 
)

Creates a directory.

Parameters:
[in]nameDirectory file name to create.
[in]modeFile mode to create the directory.
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded.
OS_RETURN_CODE_FILE_EXISTDirectory exists.
OS_RETURN_CODE_FILE_OPEN_FAILEDIf the operation failed.
Availability:
O/S: Windows, Linux & macOS*
CPU: All
OS_RETURN_CODE OS_OpenDirFD ( const CHAR *  name,
NATIVE_FD fd 
)

Opens a directory for browsing.

Parameters:
[in]nameDirectory file name to open.
[out]fdPointer to returned file descriptor.
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_OPEN_FAILEDIf the operation failed
Availability:
O/S: Windows, Linux & macOS*
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]pathFile path.
[in]flagsor'ed OS_FILE_OPEN_TYPE. If mode OS_FILE_OPEN_TYPE_CREATE
was given, the file is created with mode.
[in]modeIf 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]fdReturned file descriptor
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_OPEN_FAILEDIf the operation Failed
Returns:
fd - Assigned with the file descriptor
Availability:
O/S: Windows, Linux & macOS*
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]fdFile descriptor
[in,out]countBytes to read/Bytes read
[out]bufferOutput buffer
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_READ_FAILEDIf 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 & macOS*
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]fdFile descriptor
[in,out]countBytes to read
[out]bufferOutput buffer
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_READ_FAILEDIf 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 & macOS*
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]pathPath to the symbolic link to read.
[out]bufThe path where the symlink points to.
[in,out]sizeThe number of bytes in buf, returns the number of bytes filled inside buf.
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded.
OS_RETURN_CODE_FILE_QUERY_FAILEDIf the operation failed.
Availability:
O/S: Linux & macOS*
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]fdFile descriptor to relocate and record.
Availability:
O/S: Linux & macOS*
CPU: All
OS_RETURN_CODE OS_RenameFile ( const CHAR *  oldPath,
const CHAR *  newPath 
)

Renamed the file oldPath to newPath

Parameters:
[in]oldPathFilename to rename
[in]newPathNew filename to rename to
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_OPERATION_FAILEDIf the operation failed
Availability:
O/S: Windows, Linux & macOS*
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]fdFile descriptor to record.
Availability:
O/S: Linux & macOS*
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]fdFile descriptor to record.
Availability:
O/S: Linux & macOS*
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]fdFile descriptor
[in]whenceOS_FILE_SEEK_TYPE
[in,out]offsetBytes to move
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_SEEK_FAILEDIf the operation failed
Returns:
offset - Assigned with the number of bytes successfully read
Availability:
O/S: Windows, Linux & macOS*
CPU: All
BOOL_T OS_WasFileReportedOpen ( NATIVE_FD  fd)

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

Parameters:
[in]fdFile descriptor to query.
Availability:
O/S: Linux & macOS*
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]fdFile descriptor
[in]bufferData buffer
[in,out]countBytes to write
Return values:
OS_RETURN_CODE_NO_ERRORIf the operation succeeded
OS_RETURN_CODE_FILE_WRITE_FAILEDIf the operation failed
Returns:
size Assigned with the number of bytes successfully written
Availability:
O/S: Windows, Linux & macOS*
CPU: All
 All Classes Variables