CFFileDescriptor Reference

Overview

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 by Task

Creating a CFFileDescriptor

• CFFileDescriptorCreate

Getting Information About a File Descriptor

• CFFileDescriptorGetNativeDescriptor
• CFFileDescriptorIsValid
• CFFileDescriptorGetContext

Invalidating a File Descriptor

• CFFileDescriptorInvalidate

Managing Callbacks

• CFFileDescriptorEnableCallBacks
• CFFileDescriptorDisableCallBacks

Creating a Run Loop Source

• CFFileDescriptorCreateRunLoopSource

Getting the CFFileDescriptor Type ID

• CFFileDescriptorGetTypeID

Functions

CFFileDescriptorCreate

Creates a new CFFileDescriptor.

CFFileDescriptorRef CFFileDescriptorCreate (
   CFAllocatorRef allocator,
   CFFileDescriptorNativeDescriptor fd,
   Boolean closeOnInvalidate,
   CFFileDescriptorCallBack callout,
   const CFFileDescriptorContext *context
);

CFFileDescriptorCreateRunLoopSource

Creates a new runloop source for a given CFFileDescriptor.

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

CFFileDescriptorDisableCallBacks

Disables callbacks for a given CFFileDescriptor.

void CFFileDescriptorDisableCallBacks (
   CFFileDescriptorRef f,
   CFOptionFlags callBackTypes
);

CFFileDescriptorEnableCallBacks

Enables callbacks for a given CFFileDescriptor.

void CFFileDescriptorEnableCallBacks (
   CFFileDescriptorRef f,
   CFOptionFlags callBackTypes
);

CFFileDescriptorGetContext

Gets the context for a given CFFileDescriptor.

void CFFileDescriptorGetContext (
   CFFileDescriptorRef f,
   CFFileDescriptorContext *context
);

CFFileDescriptorGetNativeDescriptor

Returns the native file descriptor for a given CFFileDescriptor.

CFFileDescriptorNativeDescriptor CFFileDescriptorGetNativeDescriptor (
   CFFileDescriptorRef f
);

CFFileDescriptorGetTypeID

Returns the type identifier for the CFFileDescriptor opaque type.

CFTypeID CFFileDescriptorGetTypeID (
   void
);

CFFileDescriptorInvalidate

Invalidates a CFFileDescriptor object.

void CFFileDescriptorInvalidate (
   CFFileDescriptorRef f,
);

CFFileDescriptorIsValid

Returns a Boolean value that indicates whether the native file descriptor for a given CFFileDescriptor is valid.

Boolean CFFileDescriptorIsValid (
   CFFileDescriptorRef f,
);

Data Types

CFFileDescriptorNativeDescriptor

Defines a type for the native file descriptor.

typedef int CFFileDescriptorNativeDescriptor;

CFFileDescriptorCallBack

Defines a structure for a callback for a CFFileDescriptor.

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

CFFileDescriptorContext

Defines a structure for the context of a CFFileDescriptor.

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

Fields

version

The version number of this structure. If not one of the defined version numbers for this opaque type, the behavior is undefined. The current version of this structure is 0.

info

retain

The retain callback used by the CFFileDescriptor.

release

The release callback used by the CFFileDescriptor.

copyDescription

The callback used to create a descriptive string representation of the CFFileDescriptor.

CFFileDescriptorRef

A reference to an CFFileDescriptor object.

typedef struct __CFFileDescriptor * CFFileDescriptorRef;

Constants

Callback Identifiers

Constants that identify the read and write callbacks.

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

Constants

kCFFileDescriptorReadCallBack

Identifies the read callback.

Available in OS X v10.5 and later.

Declared in CFFileDescriptor.h.

kCFFileDescriptorWriteCallBack

Identifies the write callback.

Available in OS X v10.5 and later.

Declared in CFFileDescriptor.h.