Add overloads to cover dup3 and pipe2 POSIX APIs

This follows the existing pattern of wrapping dup/dup2 and pipe with FileDescriptor.duplicate and FileDescriptor.pipe, with additional overloads for passing the O_CLOEXEC and similar flags.

Author: jakepetroules

Sources/CSystem/include/CSystemLinux.h

@@ -8,7 +8,7 @@
 */
 
 #ifdef __linux__
-
+#define _GNU_SOURCE
 #include <sys/epoll.h>
 #include <sys/eventfd.h>
 #include <sys/stat.h>

Sources/System/FileDescriptor.swift

@@ -324,6 +324,129 @@ extension FileDescriptor {
 #endif
   }
 
+  /// Options that specify behavior for a newly-created pipe.
+  @frozen
+  public struct PipeOptions: OptionSet, Sendable, Hashable, Codable {
+    /// The raw C options.
+    @_alwaysEmitIntoClient
+    public var rawValue: CInt
+
+    /// Create a strongly-typed options value from raw C options.
+    @_alwaysEmitIntoClient
+    public init(rawValue: CInt) { self.rawValue = rawValue }
+
+#if !os(Windows) && !canImport(Darwin)
+    /// Indicates that all
+    /// subsequent input and output operations on the pipe's file descriptors will be nonblocking.
+    ///
+    /// The corresponding C constant is `O_NONBLOCK`.
+    @_alwaysEmitIntoClient
+    public static var nonBlocking: OpenOptions { .init(rawValue: _O_NONBLOCK) }
+
+    @_alwaysEmitIntoClient
+    @available(*, unavailable, renamed: "nonBlocking")
+    public static var O_NONBLOCK: OpenOptions { nonBlocking }
+
+    /// Indicates that executing a program closes the file.
+    ///
+    /// Normally, file descriptors remain open
+    /// across calls to the `exec(2)` family of functions.
+    /// If you specify this option,
+    /// the file descriptor is closed when replacing this process
+    /// with another process.
+    ///
+    /// The state of the file
+    /// descriptor flags can be inspected using `F_GETFD`,
+    /// as described in the `fcntl(2)` man page.
+    ///
+    /// The corresponding C constant is `O_CLOEXEC`.
+    @_alwaysEmitIntoClient
+    public static var closeOnExec: OpenOptions { .init(rawValue: _O_CLOEXEC) }
+
+    @_alwaysEmitIntoClient
+    @available(*, unavailable, renamed: "closeOnExec")
+    public static var O_CLOEXEC: OpenOptions { closeOnExec }
+
+#if !os(WASI) && !os(Linux) && !os(Android)
+    /// Indicates that forking a program closes the file.
+    ///
+    /// Normally, file descriptors remain open
+    /// across calls to the `fork(2)` function.
+    /// If you specify this option,
+    /// the file descriptor is closed when forking this process
+    /// into another process.
+    ///
+    /// The state of the file
+    /// descriptor flags can be inspected using `F_GETFD`,
+    /// as described in the `fcntl(2)` man page.
+    ///
+    /// The corresponding C constant is `O_CLOFORK`.
+    @_alwaysEmitIntoClient
+    public static var closeOnFork: OpenOptions { .init(rawValue: _O_CLOFORK) }
+
+    @_alwaysEmitIntoClient
+    @available(*, unavailable, renamed: "closeOnFork")
+    public static var O_CLOFORK: OpenOptions { closeOnFork }
+#endif
+#endif
+  }
+
+  /// Options that specify behavior for a duplicated file descriptor.
+  @frozen
+  public struct DuplicateOptions: OptionSet, Sendable, Hashable, Codable {
+    /// The raw C options.
+    @_alwaysEmitIntoClient
+    public var rawValue: CInt
+
+    /// Create a strongly-typed options value from raw C options.
+    @_alwaysEmitIntoClient
+    public init(rawValue: CInt) { self.rawValue = rawValue }
+
+#if !os(Windows) && !canImport(Darwin)
+    /// Indicates that executing a program closes the file.
+    ///
+    /// Normally, file descriptors remain open
+    /// across calls to the `exec(2)` family of functions.
+    /// If you specify this option,
+    /// the file descriptor is closed when replacing this process
+    /// with another process.
+    ///
+    /// The state of the file
+    /// descriptor flags can be inspected using `F_GETFD`,
+    /// as described in the `fcntl(2)` man page.
+    ///
+    /// The corresponding C constant is `O_CLOEXEC`.
+    @_alwaysEmitIntoClient
+    public static var closeOnExec: OpenOptions { .init(rawValue: _O_CLOEXEC) }
+
+    @_alwaysEmitIntoClient
+    @available(*, unavailable, renamed: "closeOnExec")
+    public static var O_CLOEXEC: OpenOptions { closeOnExec }
+
+#if !os(WASI) && !os(Linux) && !os(Android)
+    /// Indicates that forking a program closes the file.
+    ///
+    /// Normally, file descriptors remain open
+    /// across calls to the `fork(2)` function.
+    /// If you specify this option,
+    /// the file descriptor is closed when forking this process
+    /// into another process.
+    ///
+    /// The state of the file
+    /// descriptor flags can be inspected using `F_GETFD`,
+    /// as described in the `fcntl(2)` man page.
+    ///
+    /// The corresponding C constant is `O_CLOFORK`.
+    @_alwaysEmitIntoClient
+    public static var closeOnFork: OpenOptions { .init(rawValue: _O_CLOFORK) }
+
+    @_alwaysEmitIntoClient
+    @available(*, unavailable, renamed: "closeOnFork")
+    public static var O_CLOFORK: OpenOptions { closeOnFork }
+#endif
+#endif
+  }
+
   /// Options for specifying what a file descriptor's offset is relative to.
   @frozen
   @available(System 0.0.1, *)

Sources/System/FileOperations.swift

@@ -403,17 +403,59 @@ extension FileDescriptor {
     as target: FileDescriptor? = nil,
     retryOnInterrupt: Bool = true
   ) throws -> FileDescriptor {
-    try _duplicate(as: target, retryOnInterrupt: retryOnInterrupt).get()
+    try _duplicate(as: target, options: [], retryOnInterrupt: retryOnInterrupt).get()
+  }
+
+  /// Duplicates this file descriptor and return the newly created copy.
+  ///
+  /// - Parameters:
+  ///   - `target`: The desired target file descriptor.
+  ///   - `options`: The behavior for creating the target file descriptor.
+  ///   - retryOnInterrupt: Whether to retry the write operation
+  ///      if it throws ``Errno/interrupted``. The default is `true`.
+  ///      Pass `false` to try only once and throw an error upon interruption.
+  /// - Returns: The new file descriptor.
+  ///
+  /// If the `target` descriptor is already in use, then it is first
+  /// deallocated as if a close(2) call had been done first.
+  ///
+  /// File descriptors are merely references to some underlying system resource.
+  /// The system does not distinguish between the original and the new file
+  /// descriptor in any way. For example, read, write and seek operations on
+  /// one of them also affect the logical file position in the other, and
+  /// append mode, non-blocking I/O and asynchronous I/O options are shared
+  /// between the references. If a separate pointer into the file is desired,
+  /// a different object reference to the file must be obtained by issuing an
+  /// additional call to `open`.
+  ///
+  /// However, each file descriptor maintains its own close-on-exec flag.
+  ///
+  ///
+  /// The corresponding C function is `dup3`.
+  @_alwaysEmitIntoClient
+  @available(System 0.0.2, *)
+  public func duplicate(
+    as target: FileDescriptor,
+    options: DuplicateOptions,
+    retryOnInterrupt: Bool = true
+  ) throws -> FileDescriptor {
+    try _duplicate(as: target, options: options, retryOnInterrupt: retryOnInterrupt).get()
   }
 
   @available(System 0.0.2, *)
   @usableFromInline
   internal func _duplicate(
     as target: FileDescriptor?,
+    options: DuplicateOptions,
     retryOnInterrupt: Bool
   ) throws -> Result<FileDescriptor, Errno> {
     valueOrErrno(retryOnInterrupt: retryOnInterrupt) {
       if let target = target {
+        #if !os(Windows) && !canImport(Darwin)
+        if !options.isEmpty {
+          return system_dup3(self.rawValue, target.rawValue, options.rawValue)
+        }
+        #endif
         return system_dup2(self.rawValue, target.rawValue)
       }
       return system_dup(self.rawValue)
@@ -431,6 +473,12 @@ extension FileDescriptor {
   public func dup2() throws -> FileDescriptor {
     fatalError("Not implemented")
   }
+
+  @_alwaysEmitIntoClient
+  @available(*, unavailable, renamed: "duplicate")
+  public func dup3() throws -> FileDescriptor {
+    fatalError("Not implemented")
+  }
 }
 #endif
 
@@ -445,21 +493,46 @@ extension FileDescriptor {
   @_alwaysEmitIntoClient
   @available(System 1.1.0, *)
   public static func pipe() throws -> (readEnd: FileDescriptor, writeEnd: FileDescriptor) {
-    try _pipe().get()
+    try _pipe(options: []).get()
+  }
+
+  /// Creates a unidirectional data channel, which can be used for interprocess communication.
+  ///
+  /// - Parameters:
+  ///   - options: The behavior for creating the pipe.
+  ///
+  /// - Returns: The pair of file descriptors.
+  ///
+  /// The corresponding C function is `pipe2`.
+  @_alwaysEmitIntoClient
+  @available(/*System 1.1.0: macOS 12.3, iOS 15.4, watchOS 8.5, tvOS 15.4*/iOS 8, *)
+  public static func pipe(options: PipeOptions) throws -> (readEnd: FileDescriptor, writeEnd: FileDescriptor) {
+    try _pipe(options: options).get()
   }
 
   @available(System 1.1.0, *)
   @usableFromInline
-  internal static func _pipe() -> Result<(readEnd: FileDescriptor, writeEnd: FileDescriptor), Errno> {
+  internal static func _pipe(options: PipeOptions) -> Result<(readEnd: FileDescriptor, writeEnd: FileDescriptor), Errno> {
     var fds: (Int32, Int32) = (-1, -1)
     return withUnsafeMutablePointer(to: &fds) { pointer in
       pointer.withMemoryRebound(to: Int32.self, capacity: 2) { fds in
         valueOrErrno(retryOnInterrupt: false) {
-          system_pipe(fds)
+          #if !os(Windows) && !canImport(Darwin)
+          if !options.isEmpty {
+            return system_pipe2(fds, options.rawValue)
+          }
+          #endif
+          return system_pipe(fds)
         }.map { _ in (.init(rawValue: fds[0]), .init(rawValue: fds[1])) }
       }
     }
   }
+
+  @_alwaysEmitIntoClient
+  @available(*, unavailable, renamed: "pipe")
+  public func pipe2() throws -> FileDescriptor {
+    fatalError("Not implemented")
+  }
 }
 #endif
 

Sources/System/Internals/Constants.swift

@@ -621,6 +621,11 @@ internal var _O_SYMLINK: CInt { O_SYMLINK }
 #if !os(Windows)
 @_alwaysEmitIntoClient
 internal var _O_CLOEXEC: CInt { O_CLOEXEC }
+
+#if !os(WASI) && !os(Linux) && !os(Android) && !canImport(Darwin)
+@_alwaysEmitIntoClient
+internal var _O_CLOFORK: CInt { O_CLOFORK }
+#endif
 #endif
 
 @_alwaysEmitIntoClient

Sources/System/Internals/Syscalls.swift

@@ -10,6 +10,7 @@
 #if SYSTEM_PACKAGE_DARWIN
 import Darwin
 #elseif canImport(Glibc)
+import CSystem
 import Glibc
 #elseif canImport(Musl)
 import Musl
@@ -139,6 +140,15 @@ internal func system_dup2(_ fd: Int32, _ fd2: Int32) -> Int32 {
   #endif
   return dup2(fd, fd2)
 }
+
+#if !os(Windows) && !canImport(Darwin)
+internal func system_dup3(_ fd: Int32, _ fd2: Int32, _ oflag: Int32) -> Int32 {
+  #if ENABLE_MOCKING
+  if mockingEnabled { return _mock(fd, fd2, oflag) }
+  #endif
+  return dup3(fd, fd2, oflag)
+}
+#endif
 #endif
 
 #if !os(WASI)
@@ -148,6 +158,15 @@ internal func system_pipe(_ fds: UnsafeMutablePointer<Int32>) -> CInt {
 #endif
   return pipe(fds)
 }
+
+#if !os(Windows) && !canImport(Darwin)
+internal func system_pipe2(_ fds: UnsafeMutablePointer<Int32>, _ oflag: Int32) -> CInt {
+#if ENABLE_MOCKING
+  if mockingEnabled { return _mock(fds, oflag) }
+#endif
+  return pipe2(fds, oflag)
+}
+#endif
 #endif
 
 internal func system_ftruncate(_ fd: Int32, _ length: off_t) -> Int32 {