newfd

newfd is a term used in some C libraries and code bases to describe a non-standard helper function that returns a new file descriptor referring to the same open file as an existing descriptor. It is not part of the POSIX standard and its exact behavior can vary between implementations, so portable code should treat it as non-guaranteed.

Typical implementations wrap lower-level file descriptor operations such as dup or fcntl. A common approach is to duplicate oldfd into the lowest available descriptor, using the fcntl system call with the F_DUPFD (or F_DUPFD_CLOEXEC) flag when available. This can allow the new descriptor to start at a specified minimum value and, in some variants, automatically set the close-on-exec flag to prevent descriptor leakage across exec calls. If F_DUPFD_CLOEXEC is not available, a port may fall back to dup and then apply FD_CLOEXEC with fcntl.

Return value and errors are system-dependent but generally follow standard semantics: on success, newfd returns a non-negative integer representing the new descriptor; on failure, it returns -1 and sets errno accordingly.

use cases for newfd typically involve scenarios where a program needs a separate descriptor for the same underlying file description without altering the original descriptor (for example, when preparing to pass a descriptor to a child process or when managing descriptor lifetimes within a library). Because newfd is not standardized, developers should rely on portable alternatives such as dup, dup2, or dup3, and, when cross-platform behavior is required, implement a library-local wrapper that uses the appropriate system calls available on the target platform.

See also: dup, dup2, dup3, fcntl, FD_CLOEXEC.