fileport_makeport(2)

NAME

fileport_makeport, fileport_makefd – manipulate fileports

SYNOPSIS

#include <sys/fileport.h>

int

fileport_makeport(int fildes, fileport_t *port);

int

fileport_makefd(fileport_t port);

DESCRIPTION

A fileport is a flavor of Mach port that implicitly contains a reference to an existing open file description. The fileport_makeport() 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 fileport_makeport(), 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 fileport_makefd() 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 fileport_makefd() until either the fileport is deallocated or a descriptor limit is exceeded.

NOTES

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; fileport_makeport() 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.

RETURN VALUES

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.

ERRORS

The fileport_makeport() system call will fail if:

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

The fileport_makefd() system call will fail if:

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