The VFS kernel extension and the user space API are communicating via an internal unix socket. This article describes the proprietary protocol used for the communication and should be used as reference to analyse data packages and/or extend the protocol.
Introduction
The user space API operates as server and the kernel extension as client. Every time a user space application mounts a VFS drive, it tells the server the socket address it should connect to. If the kernel extension is initialized, it opens a new connection to the user space API.
Each request is send from kernel space to user space and each request expects a reply from the user space.
Datagrams
All datagrams are divided into a header field and some optional payload data.
--------+---+---+---+---+---+---+---+---+--------
| |
| HEADER |
| |
--+---+---+---+---+---+---+---+---+--
| |
| PAYLOAD |
| |
--------+---+---+---+---+---+---+---+---+--------
HEADER
The CenshareFSRequestHead represent the first bytes of every request send from the kernel extension to the User-Space API.
--------+---+---+---+---+---+---+---+---+--------
| Request Type | enum (= int)
+---+---+---+---+---+---+---+---+
| Request Sequence Number | uint32
+---+---+---+---+---+---+---+---+
| Context Process ID | int32
+---+---+---+---+---+---+---+---+
| Context User ID | uid_t (= uint32)
+---+---+---+---+---+---+---+---+
| Context Group ID | gid_t (= uint32)
+---+---+---+---+---+---+---+---+
| Context Node ID | uint64
--------+---+---+---+---+---+---+---+---+--------
The first entry in the header specifies the request type. It specifies the type of datagram and therefore the values which are stored within the payload. The different request types are explained within the next chapter.
The second entry is the sequence number which identifies the number of the current running request. The sequence number is incremented by one for each new request.
The next four entries are defining a context for the send request. It contains out of:
- Process ID - The process id of the executing process (e.g. the pid of the "Finder")
- User ID - The id of the user the process is running on.
- Group ID - The default id of the group the process is running on.
- Node ID - The current ID of the node on which the request should operate on.
The CenshareFSReplyHead represent the first bytes of every request send from the User-Space API back to the kernel extension.
--------+---+---+---+---+---+---+---+---+--------
| Request Type | enum (= int)
+---+---+---+---+---+---+---+---+
| Request Sequence Number | uint32
+---+---+---+---+---+---+---+---+
| Reply Status Code | int32
--------+---+---+---+---+---+---+---+---+--------
The values request type and request sequence number are mirrored from the request datagram.
The reply status code is an integer value which specifies the success of the result of the executed request. Please see errno.h for possible values.
DATAGRAMS
The datagrams are divided into two different types.
The FS commands are commands executed on filesystem level for example to tell the user space API that the VFS was unmounted or that someone wants to get some filesystem information like the total amount of storage space.
The VNode commands are commands which operate on nodes of the filesystem and a node is a directory or a file itself.
(1) FS Commands
(1.1) Unmount
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnLookup (= 0x0100)
CenshareFSRequestHead
| |
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| |
CenshareFSReplyHead
| |
--------+---+---+---+---+---+---+---+---+--------
(1.2) Getattr
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdFsUnmount (= 0x0002)
CenshareFSRequestHead
| |
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| |
CenshareFSReplyHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSReplyFSAttr | Number of available bytes | uint64 // Total capacity of the FS
+---+---+---+---+---+---+---+---+
| Number of used bytes | uint64 // Total amount of used bytes
+---+---+---+---+---+---+---+---+
| Max number of possible nodes| uint64 // Number of allowd objects
+---+---+---+---+---+---+---+---+ (files & directories)
| Number of file objects | uint64 // All files on disk
+---+---+---+---+---+---+---+---+
| Number of directories | uint64 // All directories on disk
+---+---+---+---+---+---+---+---+ (excluding root)
| Time of creation | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last modification | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last access | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last backup | struct timespec
--------+---+---+---+---+---+---+---+---+--------
(1.3) VGet
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdFsVGet (= 0x000a)
CenshareFSRequestHead
| |
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| |
CenshareFSReplyHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSReplyFsVGet | Number of references | uint64 // 1= regular file,
+---+---+---+---+---+---+---+---+ n= entries in a directory
| Size of data | uint64 // 0= directory, n= num of bytes
+---+---+---+---+---+---+---+---+
| Time of creation | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last access | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last data mod. | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last metadata mod. | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last backup | struct timespec
+---+---+---+---+---+---+---+---+
| User ID of node owner | uid_t (= uint32)
+---+---+---+---+---+---+---+---+
| Group ID of node owner | gid_t (= uint32)
+---+---+---+---+---+---+---+---+
| Posix permissions | mode_t (=uint16)
+---+---+---+---+---+---+---+---+
| Node ID | uint64
+---+---+---+---+---+---+---+---+
| Node Type | enum (= int) // CenshareFSEntryTypeDirectory or
+---+---+---+---+---+---+---+---+ CenshareFSEntryTypeRegularFile
| Length of found name | int64
+---+---+---+---+---+---+---+---+
| Found name | char[255]
--------+---+---+---+---+---+---+---+---+--------
(2) VNode Commands
(2.1) Lookup
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnLookup (= 0x0100)
CenshareFSRequestHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSRequestLookup | Offset to start with read | uint64
+---+---+---+---+---+---+---+---+
| Num of chars to be read | uint64
+---+---+---+---+---+---+---+---+
| Length of lookup path | uint64
+---+---+---+---+---+---+---+---+
| |
Lookup path CsBytes (length sequential chars)
| |
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| |
CenshareFSReplyHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSReplyLookup | Number of references | uint64 // 1= regular file,
+---+---+---+---+---+---+---+---+ n= entries in a directory
| Size of data | uint64 // 0= directory, n= num of bytes
+---+---+---+---+---+---+---+---+
| Time of creation | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last access | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last data mod. | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last metadata mod. | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last backup | struct timespec
+---+---+---+---+---+---+---+---+
| User ID of node owner | uid_t (= uint32)
+---+---+---+---+---+---+---+---+
| Group ID of node owner | gid_t (= uint32)
+---+---+---+---+---+---+---+---+
| Posix permissions | mode_t (=uint16)
+---+---+---+---+---+---+---+---+
| Node ID | uint64
+---+---+---+---+---+---+---+---+
| Node Type | enum (= int) // CenshareFSEntryTypeDirectory or
+---+---+---+---+---+---+---+---+ CenshareFSEntryTypeRegularFile
| Length of found name | int64
+---+---+---+---+---+---+---+---+
| Found name | char[255]
--------+---+---+---+---+---+---+---+---+--------
(2.2) Open
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnOpen (= 0x0300)
CenshareFSRequestHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSRequestOpen | Open mode | uint32 // FREAD and/or FWRITE
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| |
CenshareFSReplyHead
| |
--------+---+---+---+---+---+---+---+---+--------
(2.3) Close
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnClose (= 0x0400)
CenshareFSRequestHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSRequestClose | Close mode | uint32 // FREAD and/or FWRITE
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| |
CenshareFSReplyHead
| |
--------+---+---+---+---+---+---+---+---+--------
(2.4) Getattr
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnGetattr (= 0x0500)
CenshareFSRequestHead
| |
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| |
CenshareFSReplyHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSReplyGetattr | Number of references | uint64 // 1= regular file,
+---+---+---+---+---+---+---+---+ n= entries in a directory
| Size of data | uint64 // 0= directory, n= num of bytes
+---+---+---+---+---+---+---+---+
| Time of creation | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last access | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last data mod. | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last metadata mod. | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last backup | struct timespec
+---+---+---+---+---+---+---+---+
| User ID of node owner | uid_t (= uint32)
+---+---+---+---+---+---+---+---+
| Group ID of node owner | gid_t (= uint32)
+---+---+---+---+---+---+---+---+
| Posix permissions | mode_t (=uint16)
+---+---+---+---+---+---+---+---+
| Node ID | uint64
+---+---+---+---+---+---+---+---+
| Node Type | enum (= int) // CenshareFSEntryTypeDirectory or
+---+---+---+---+---+---+---+---+ CenshareFSEntryTypeRegularFile
| Length of found name | int64
+---+---+---+---+---+---+---+---+
| Found name | char[255]
--------+---+---+---+---+---+---+---+---+--------
(2.5) Read
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnRead (= 0x0700)
CenshareFSRequestHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSRequestRead | Offset to start with read | off_t (= int64)
+---+---+---+---+---+---+---+---+
| Num of bytes to be read | user_ssize_t (= int64)
+---+---+---+---+---+---+---+---+
| I/O Flags | int32
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| |
CenshareFSReplyHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSReplyRead | Num of read bytes | user_ssize_t (= int64)
+---+---+---+---+---+---+---+---+
| |
Read bytes n * sizeof(char) // size of this field is
| | defined by user_ssize_t
--------+---+---+---+---+---+---+---+---+--------
(2.6) Readdir
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnReaddir (= 0x0c00)
CenshareFSRequestHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSRequestReaddir| Offset to start with read | off_t (= int64) // 0= first file, n= nth file
+---+---+---+---+---+---+---+---+
| Num of nodes to return | user_ssize_t (= int64)
+---+---+---+---+---+---+---+---+
| I/O Flags | int32
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnLookup (= 0x0100)
CenshareFSReplyHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSReplyReaddir | Are all nodes returned (?) | boolean_t (= int) // 1= all nodes read,
+---+---+---+---+---+---+---+---+ 0= pending nodes
| Num of returned nodes | user_ssize_t (= int64)
-- -+---+---+---+---+---+---+---+---+-
| | Node ID | uint64
| +---+---+---+---+---+---+---+---+
| | Node Type | enum (= int) // CenshareFSEntryTypeDirectory or
Node 1 --| +---+---+---+---+---+---+---+---+ CenshareFSEntryTypeRegularFile
| | Length of found name | int64
| +---+---+---+---+---+---+---+---+
| | Found name | char[255]
-- -+---+---+---+---+---+---+---+---+-
| | Node ID | uint64
| +---+---+---+---+---+---+---+---+
| | Node Type | enum (= int) // CenshareFSEntryTypeDirectory or
Node 2 --| +---+---+---+---+---+---+---+---+ CenshareFSEntryTypeRegularFile
| | Length of found name | int64
| +---+---+---+---+---+---+---+---+
| | Found name | char[255]
-- -+---+---+---+---+---+---+---+---+-
| |
| |
--------+---+---+---+---+---+---+---+---+--------
(2.7) Create
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnCreate (= )
CenshareFSRequestHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSRequestCreate | Length of name | uint64
+---+---+---+---+---+---+---+---+
| |
Creation name CsBytes (length sequential chars)
| |
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnCreate (=)
CenshareFSReplyHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSReplyGetattr | Number of references | uint64 // 1= regular file,
+---+---+---+---+---+---+---+---+ n= entries in a directory
| Size of data | uint64 // 0= directory, n= num of bytes
+---+---+---+---+---+---+---+---+
| Time of creation | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last access | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last data mod. | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last metadata mod. | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last backup | struct timespec
+---+---+---+---+---+---+---+---+
| User ID of node owner | uid_t (= uint32)
+---+---+---+---+---+---+---+---+
| Group ID of node owner | gid_t (= uint32)
+---+---+---+---+---+---+---+---+
| Posix permissions | mode_t (=uint16)
+---+---+---+---+---+---+---+---+
| Node ID | uint64
+---+---+---+---+---+---+---+---+
| Node Type | enum (= int) // CenshareFSEntryTypeDirectory or
+---+---+---+---+---+---+---+---+ CenshareFSEntryTypeRegularFile
| Length of found name | int64
+---+---+---+---+---+---+---+---+
| Found name | char[255]
--------+---+---+---+---+---+---+---+---+--------
(2.8) Write
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnWrite (= )
CenshareFSRequestHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSRequestWrite | Offset to start with write | off_t (= int64)
+---+---+---+---+---+---+---+---+
| Num of bytes to be written | user_ssize_t (= int64)
+---+---+---+---+---+---+---+---+
| I/O Flags | int32
+---+---+---+---+---+---+---+---+
| |
Write bytes n * sizeof(char) // size of this field is
| | defined by user_ssize_t
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| |
CenshareFSReplyHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSReplyWrite | Num of written bytes | user_ssize_t (= int64)
--------+---+---+---+---+---+---+---+---+--------
(2.9) Fsync
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnFsync (= )
CenshareFSRequestHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSRequestFSync | WaitFor | uint32 // ???
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| |
CenshareFSReplyHead
| |
--------+---+---+---+---+---+---+---+---+--------
(2.10) Remove
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnRemove (= )
CenshareFSRequestHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSRequestRemove | Node ID (file to delete) | uint64
+---+---+---+---+---+---+---+---+
| Length of name | uint64
+---+---+---+---+---+---+---+---+
| |
Name of file to delete CsBytes (length sequential chars)
| |
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| |
CenshareFSReplyHead
| |
--------+---+---+---+---+---+---+---+---+--------
(2.11) Rename
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnRename (= )
CenshareFSRequestHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSRequestRename | SRC Node ID | uint64 (file to be renamed)
+---+---+---+---+---+---+---+---+
| Length of src-name | uint64 (namelen of file to be renamed)
+---+---+---+---+---+---+---+---+
| |
SRC-name to be renamed CsBytes (name of file to be renamed)
| |
+---+---+---+---+---+---+---+---+
| DST Node ID | uint64 (destination DIR ID)
+---+---+---+---+---+---+---+---+
| EXISTING Node ID | uint64 (existing file with same name in dst)
+---+---+---+---+---+---+---+---+
| Length of src-name | uint64 (namelen of new name)
+---+---+---+---+---+---+---+---+
| |
DST-name to be named to CsBytes (new name of file)
| |
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| |
CenshareFSReplyHead
| |
--------+---+---+---+---+---+---+---+---+--------
(2.12) Mkdir
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnMkdir (= )
CenshareFSRequestHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSRequestMkdir | Length of name | uint64
+---+---+---+---+---+---+---+---+
| |
Creation name CsBytes (length sequential chars)
| |
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnMkdir (=)
CenshareFSReplyHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSReplyGetattr | Number of references | uint64 // 1= regular file,
+---+---+---+---+---+---+---+---+ n= entries in a directory
| Size of data | uint64 // 0= directory, n= num of bytes
+---+---+---+---+---+---+---+---+
| Time of creation | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last access | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last data mod. | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last metadata mod. | struct timespec
+---+---+---+---+---+---+---+---+
| Time of last backup | struct timespec
+---+---+---+---+---+---+---+---+
| User ID of node owner | uid_t (= uint32)
+---+---+---+---+---+---+---+---+
| Group ID of node owner | gid_t (= uint32)
+---+---+---+---+---+---+---+---+
| Posix permissions | mode_t (=uint16)
+---+---+---+---+---+---+---+---+
| Node ID | uint64
+---+---+---+---+---+---+---+---+
| Node Type | enum (= int) // CenshareFSEntryTypeDirectory or
+---+---+---+---+---+---+---+---+ CenshareFSEntryTypeRegularFile
| Length of found name | int64
+---+---+---+---+---+---+---+---+
| Found name | char[255]
--------+---+---+---+---+---+---+---+---+--------
(2.13) Rmdir
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnRmDir (= )
CenshareFSRequestHead
| |
--+---+---+---+---+---+---+---+---+--
CenshareFSRequestRmDir | Node ID (dir to delete) | uint64
+---+---+---+---+---+---+---+---+
| Length of name | uint64
+---+---+---+---+---+---+---+---+
| |
Name of dir to delete CsBytes (length sequential chars)
| |
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| |
CenshareFSReplyHead
| |
--------+---+---+---+---+---+---+---+---+--------
(2.14) Inactive
Request:
--------+---+---+---+---+---+---+---+---+--------
| | Request Type = CenshareFSCmdVnInactive (= )
CenshareFSRequestHead
| |
--------+---+---+---+---+---+---+---+---+--------
Reply:
--------+---+---+---+---+---+---+---+---+--------
| |
CenshareFSReplyHead
| |
--------+---+---+---+---+---+---+---+---+--------