FILEPORT_MAKEPORT(2) System Calls Manual FILEPORT_MAKEPORT(2)

fileport_makeport, fileport_makefd — manipulate fileports

#include <sys/fileport.h>

int
fileport_makeport(int fildes, fileport_t *port);

int
fileport_makefd(fileport_t port);

A fileport is a flavor of Mach port that implicitly contains a reference to an existing open file description. The () interface creates a new fileport from an open file descriptor fildes, while fileport_makefd() creates a new file descriptor from a fileport.

A valid fileport may be sent from one process to another via Mach IPC. Once the sending process has successfully created a fileport from a file descriptor with (), it may immediately close the descriptor with close(2), or use it to share the open file description with the receiver.

The receiving process should use () to create a new file descriptor from the received fileport; that descriptor will reference the same underlying open file description as the sending process. The new descriptor is created with the close-on-exec file descriptor flag enabled.

Further file descriptors can be created from the fileport using () until either the fileport is deallocated or a descriptor limit is exceeded.

Fileports are a low-level primitive, and Mach IPC can be complex. Developers who need to move file descriptors between processes are advised to use XPC and the corresponding xpc_fd_create(3) and xpc_fd_dup(3) interfaces instead.

Certain special types of open file descriptions, e.g. a kqueue, cannot be sent between processes; () will return an error for those descriptors.

The effect of using these primitives as a file descriptor IPC mechanism, as outlined above, has the same sharing semantics as other file descriptor IPC mechanisms on the platform: it is as if the original file descriptor from the sending process has been duplicated, in the sense of dup(2), into the receiving process.

If successful, fileport_makefd() returns a non-negative integer. If successful, fileport_makeport() returns 0. Otherwise on failure both interfaces return -1 and the global variable errno is set to indicate the error.

The fileport_makeport() system call will fail if:

[]
fildes is not a valid file descriptor.
[]
The file descriptor cannot be sent to another procss.
[]
Fileport address is invalid.
[]
Temporary resource shortage.

The fileport_makefd() system call will fail if:

[]
The fileport is invalid.
[]
The process has reached its open file descriptor limit.
[]
Unable to extend the file table
[]
Insufficient memory to allocate a descriptor.

xpc(3), xpc_fd_create(3), xpc_fd_dup(3), dup(2), getrlimit(2), sendmsg(2), recvmsg(2), kqueue(2)

December 20, 2024 Darwin