PinCRT
Classes | Typedefs | Enumerations | Functions
File

Classes

struct  _OS_FILE_UNIQUE_ID
 

Typedefs

typedef INT OS_FILE_PERMISSION_TYPE
 
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 {
  OS_FILE_PERMISSION_TYPE_EXECUTE_OTHERS = 0001,
  OS_FILE_PERMISSION_TYPE_WRITE_OTHERS = 0002,
  OS_FILE_PERMISSION_TYPE_READ_OTHERS = 0004,
  OS_FILE_PERMISSION_TYPE_ALL_OTHERS = 0007,
  OS_FILE_PERMISSION_TYPE_EXECUTE_GROUP = 0010,
  OS_FILE_PERMISSION_TYPE_WRITE_GROUP = 0020,
  OS_FILE_PERMISSION_TYPE_READ_GROUP = 0040,
  OS_FILE_PERMISSION_TYPE_ALL_GROUP = 0070,
  OS_FILE_PERMISSION_TYPE_EXECUTE_USER = 0100,
  OS_FILE_PERMISSION_TYPE_WRITE_USER = 0200,
  OS_FILE_PERMISSION_TYPE_READ_USER = 0400,
  OS_FILE_PERMISSION_TYPE_ALL_USER = 0700
}
 
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, OS_FILE_PERMISSION_TYPE 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, OS_FILE_PERMISSION_TYPE 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)
 

Detailed Description

Typedef Documentation

◆ OS_FILE_PERMISSION_TYPE

Bit-mask of OS_FILE_PERMISSION's

◆ OS_FILE_UNIQUE_ID

Machine unique ID for file

◆ OS_PROCESS_WAITABLE_PROCESS

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

Enumeration Type Documentation

◆ OS_FILE_ATTRIBUTES

File permission modes

◆ OS_FILE_OPEN_TYPE

File open modes

◆ OS_FILE_PERMISSION

File access permission modes (not all enums apply in Windows)

◆ 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.

◆ OS_PIPE_CREATE_FLAGS

Pipes creation flags

Function Documentation

◆ OS_Chdir()

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_CloseFD()

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_Cwd()

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_DeleteDirectory()

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_DeleteFile()

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_DuplicateFD()

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_FilePermissionsFD()

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_FileSizeFD()

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_FileUniqueID()

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_FlushFD()

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_Ftruncate()

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_GetFDAccessMode()

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_GetFDAttributes()

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_GetFileAttributes()

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

◆ OS_GetLowestFileDescriptorToUse()

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_IsConsoleFD()

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_MkDir()

OS_RETURN_CODE OS_MkDir ( const CHAR *  name,
OS_FILE_PERMISSION_TYPE  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_OpenDirFD()

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_OpenFD()

OS_RETURN_CODE OS_OpenFD ( const CHAR *  path,
INT  flags,
OS_FILE_PERMISSION_TYPE  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_ReadDirectoryFD()

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_ReadFD()

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_ReadLink()

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

◆ OS_RelocateAndReportFileOpen()

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_RenameFile()

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

◆ OS_ReportFileClose()

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

◆ OS_ReportFileOpen()

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_SeekFD()

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

◆ OS_WasFileReportedOpen()

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_WriteFD()

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