Mac Developer Library

Developer

CoreFoundation Framework Reference CFFileDescriptor Reference

Options
Deployment Target:

On This Page
Language:

CFFileDescriptor Reference

The CFFileDescriptor provides an opaque type to monitor file descriptors for read and write activity via CFRunLoop.

You use CFFileDescriptor to monitor file descriptors for read and write activity via CFRunLoop using callbacks. Each call back is one-shot, and must be re-enabled if you want to get another one.

You can re-enable the callback in the callback function itself, but you must completely service the file descriptor before doing so. For example, if you create a CFFileDescriptor for a pipe and get a callback because there are bytes to be read, then if you don't read all of the bytes but nevertheless re-enable the CFFileDescriptor for read activity, you'll get called back again immediately.

You can monitor kqueue file descriptors for read activity to find out when an event the kqueue is filtering for has occurred. You are responsible for understanding the use of the kevent() API and inserting and removing filters from the kqueue file descriptor yourself.

The following example takes a UNIX process ID as argument, and watches up to 20 seconds, and reports if the process terminates in that time:

  • // cc test.c -framework CoreFoundation -O
  • #include <CoreFoundation/CoreFoundation.h>
  • #include <unistd.h>
  • #include <sys/event.h>
  • static void noteProcDeath(CFFileDescriptorRef fdref, CFOptionFlags callBackTypes, void *info) {
  • struct kevent kev;
  • int fd = CFFileDescriptorGetNativeDescriptor(fdref);
  • kevent(fd, NULL, 0, &kev, 1, NULL);
  • // take action on death of process here
  • printf("process with pid '%u' died\n", (unsigned int)kev.ident);
  • CFFileDescriptorInvalidate(fdref);
  • CFRelease(fdref); // the CFFileDescriptorRef is no longer of any use in this example
  • }
  • // one argument, an integer pid to watch, required
  • int main(int argc, char *argv[]) {
  • if (argc < 2) exit(1);
  • int fd = kqueue();
  • struct kevent kev;
  • EV_SET(&kev, atoi(argv[1]), EVFILT_PROC, EV_ADD|EV_ENABLE, NOTE_EXIT, 0, NULL);
  • kevent(fd, &kev, 1, NULL, 0, NULL);
  • CFFileDescriptorRef fdref = CFFileDescriptorCreate(kCFAllocatorDefault, fd, true, noteProcDeath, NULL);
  • CFFileDescriptorEnableCallBacks(fdref, kCFFileDescriptorReadCallBack);
  • CFRunLoopSourceRef source = CFFileDescriptorCreateRunLoopSource(kCFAllocatorDefault, fdref, 0);
  • CFRunLoopAddSource(CFRunLoopGetMain(), source, kCFRunLoopDefaultMode);
  • CFRelease(source);
  • // run the run loop for 20 seconds
  • CFRunLoopRunInMode(kCFRunLoopDefaultMode, 20.0, false);
  • return 0;
  • }

Functions

  • Invalidates a CFFileDescriptor object.

    Declaration

    Swift

    func CFFileDescriptorInvalidate(_ f: CFFileDescriptor!)

    Objective-C

    void CFFileDescriptorInvalidate ( CFFileDescriptorRef f );

    Parameters

    f

    A CFFileDescriptor.

    Discussion

    Once invalidated, the CFFileDescriptor object will no longer be read from or written to at the Core Fundation level.

    If you passed true for the closeOnInvalidate parameter when you called CFFileDescriptorCreate, this function also closes the underlying file descriptor. If you passed false, you must close the descriptor yourself after invalidating the CFFileDescriptor object.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.5 and later.

  • Creates a new runloop source for a given CFFileDescriptor.

    Declaration

    Swift

    func CFFileDescriptorCreateRunLoopSource(_ allocator: CFAllocator!, _ f: CFFileDescriptor!, _ order: CFIndex) -> CFRunLoopSource!

    Objective-C

    CFRunLoopSourceRef CFFileDescriptorCreateRunLoopSource ( CFAllocatorRef allocator, CFFileDescriptorRef f, CFIndex order );

    Parameters

    allocator

    The allocator to use to allocate memory for the new bag and its storage for values. Pass NULL or kCFAllocatorDefault to use the current default allocator.

    f

    A CFFileDescriptor.

    order

    The order for the new run loop (see CFRunLoopSourceCreate).

    Return Value

    A new runloop source for f, or NULL if there was a problem creating the object. Ownership follows the Create Rule.

    Discussion

    The context for the new runloop (see CFRunLoopSourceCreate) is the same as the context passed in when the CFFileDescriptor was created (see CFFileDescriptorCreate).

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.5 and later.

  • Returns the type identifier for the CFFileDescriptor opaque type.

    Declaration

    Swift

    func CFFileDescriptorGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFFileDescriptorGetTypeID ( void );

    Return Value

    The type identifier for the CFFileDescriptor opaque type.

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.5 and later.

Data Types

  • Defines a type for the native file descriptor.

    Declaration

    Swift

    typealias CFFileDescriptorNativeDescriptor = Int32

    Objective-C

    typedef int CFFileDescriptorNativeDescriptor;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.5 and later.

  • Defines a structure for a callback for a CFFileDescriptor.

    Declaration

    Swift

    typealias CFFileDescriptorCallBack = CFunctionPointer<((CFFileDescriptor!, CFOptionFlags, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void (*CFFileDescriptorCallBack) ( CFFileDescriptorRef f, CFOptionFlags callBackTypes, void *info );

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.5 and later.

  • Defines a structure for the context of a CFFileDescriptor.

    Declaration

    Swift

    struct CFFileDescriptorContext { var version: CFIndex var info: UnsafeMutablePointer<Void> var retain: CFunctionPointer<((UnsafeMutablePointer<Void>) -> UnsafeMutablePointer<Void>)> var release: CFunctionPointer<((UnsafeMutablePointer<Void>) -> Void)> var copyDescription: CFunctionPointer<((UnsafeMutablePointer<Void>) -> Unmanaged<CFString>!)> }

    Objective-C

    typedef struct { CFIndex version; void * info; void * (*retain)(void *info); void (*release)(void *info); CFStringRef (*copyDescription)(void *info); } CFFileDescriptorContext;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.5 and later.

  • A reference to an CFFileDescriptor object.

    Declaration

    Swift

    typealias CFFileDescriptorRef = CFFileDescriptor

    Objective-C

    typedef struct __CFFileDescriptor * CFFileDescriptorRef;

    Import Statement

    Objective-C

    @import CoreFoundation;

    Swift

    import CoreFoundation

    Availability

    Available in OS X v10.5 and later.

Constants

  • Constants that identify the read and write callbacks.

    Declaration

    Swift

    var kCFFileDescriptorReadCallBack: Int { get } var kCFFileDescriptorWriteCallBack: Int { get }

    Objective-C

    enum { kCFFileDescriptorReadCallBack = 1 << 0, kCFFileDescriptorWriteCallBack = 1 << 1 };

    Constants

    • kCFFileDescriptorReadCallBack

      kCFFileDescriptorReadCallBack

      Identifies the read callback.

      Available in OS X v10.5 and later.

    • kCFFileDescriptorWriteCallBack

      kCFFileDescriptorWriteCallBack

      Identifies the write callback.

      Available in OS X v10.5 and later.