====== The PFS-VFS protocol ======

This page provides the official documentation of the PFS-VFS protocol of MINIX 3. It describes the protocol used between the PFS server and the VFS server. The current version documents the protocol used in SVN revision **9568**. If you update this document because of changes to MINIX 3, please mention the revision number of the change in the wiki comment.


===== General Overview =====

In order to implement file descriptor passing and better socket file permission checking, PFS has to make a few nested VFS calls. The requests are outlined below. 

==== Access Control Messages ====

=== PFS_REQ_CHECK_PERMS ===

Check Permissions.

**Request fields**

|<90%>|
|<16%  >USER_ENDPT |m2_i2|endpoint_t|The endpoint of the process that wishes to bind()/connect().|
|IO_GRANT |m2_p1|cp_grant_id_t|Path to the socket file.|
|COUNT |m2_i3|int|Length of the path.|

**Reply fields**

  * //none//

**Reply codes**
|<90%>|
|<16%  >OK |Permissions verified to be okay.|
|EACCES |Access Denied.|
|EINVAL |Invalid endpoint or strlen.|
|EIO |Couldn't copy path from grant.|
|ELOOP |More than SYMLOOP_MAX levels of symlinks were encountered when resolving the path.|
|ENOENT |File not found.|
|ENAMETOOLONG |The resolved path is too big to fit into the space provided in the grant.|

**Description**

This request asks the VFS to resolve the given path and determine if the user has permission to access it.

==== File Descriptor Passing Messages ====

=== PFS_REQ_VERIFY_FD ===

Verify a file descriptor.

**Request fields**

|<90%>|
|<16%  >USER_ENDPT|m2_i2|endpoint_t|The endpoint of the process that owns the descriptor to be verified.|
|COUNT|m2_i3|int|File descriptor number.|

**Reply fields**

|<90%>|
|<16%  >ADDRESS|m2_p1|filp_id_t|The filp that corresponds to the file descriptor.|

**Reply codes**

|<90%>|
|<16%  >OK |The file descriptor is valid.|
|EINVAL |The file descriptor is not valid.|

**Description**

Verify whether the given file descriptor is valid for the endpoint. When the file descriptor is valid a pointer to that filp is returned.

=== PFS_REQ_SET_FILP ===

Mark a filp as in-flight.

**Request fields**

|<90%>|
|<16%  >ADDRESS|m2_p1|filp_id_t|The filp that corresponds to the file descriptor.|

**Reply fields**

  * //none//

**Reply codes**

|<90%>|
|<16%  >OK |The filp was marked as in-flight.|
|EINVAL |The filp is invalid.|

**Description**

This sets a flag on the filp that prevents it from being closed while it is being copied to another process.

=== PFS_REQ_COPY_FILP ===

Copy a filp.

**Request fields**

|<90%>|
|<16%  >USER_ENDPT|m2_i2|endpoint_t|The destination.|
|ADDRESS|m2_p1|filp_id_t|The filp to be copied.|

**Reply fields**

  * //none//

**Reply codes**

|<90%>|
|<16%  >int &gt;= 0 |The new file descriptor number.|
|EINVAL|The endpoint and/or filp parameters are invalid.|
|EMFILE|The file descriptor table of the destination endpoint is full.|

**Description**

This copies a filp from one process to another.

=== PFS_REQ_PUT_FILP ===

Mark a filp as not in-flight.

**Request fields**

|<90%>|
|<16%  >ADDRESS|m2_p1|filp_id_t|The filp that corresponds to the file descriptor.|

**Reply fields**

  * //none//

**Reply codes**

|<90%>|
|<16%  >OK |The filp was marked as not in-flight.|
|EINVAL|The filp is invalid.|

**Description**

This unsets a flag on the filp that prevents it from being closed while it is being copied to another process.

=== PFS_REQ_CANCEL_FD ===

Cancel a file descriptor copy.

**Request fields**

|<90%>|
|<16%  >USER_ENDPT|m2_i2|endpoint_t|The endpoint of the process that owns the descriptor to be verified.|
|COUNT|m2_i3|int|File descriptor number.|

**Reply fields**

  * //none//

**Reply codes**

|<90%>|
|<16%  >OK |The copy was cancelled.|
|EINVAL|The file descriptor and/or endpoint parameters are invalid.||

**Description**

This reverses the changes made by <fs small>PFS_REQ_COPY_FILP</fs>.