---
name: "FileHndlr"
section: "3tk"
platform: "linux"
package: "tk40-dev"
version: "4.0p3-5"
release: "Debian 1.3 (Bo)"
platforms: ["linux"]
url: "https://new.carta.tech/FileHndlr/3tk"
---

# FileHndlr(3tk)

associate procedure callbacks with files or devices

```

```

## NAME

Tk\_CreateFileHandler, Tk\_CreateFileHandler2, Tk\_DeleteFileHandler - associate procedure callbacks with files or devices

## SYNOPSIS

```
#include <tk.h>

Tk_CreateFileHandler(id, mask, proc, clientData)

Tk_CreateFileHandler2(id, proc2, clientData)

Tk_DeleteFileHandler(id)
```

## ARGUMENTS

- int *id* (in)

  Integer identifier for an open file or device (such as returned by **open** system call).

- int *mask* (in)

  Conditions under which *proc* should be called: OR-ed combination of **TK\_READABLE**, **TK\_WRITABLE**, and **TK\_EXCEPTION**.

- Tk\_FileProc *\*proc* (in)

  Procedure to invoke whenever the file or device indicated by *id* meets the conditions specified by *mask*.

- Tk\_FileProc2 *\*proc2* (in)

  Procedure to invoke from event loop to check whether *fd* is ready and, if so, handle it.

- ClientData *clientData* (in)

  Arbitrary one-word value to pass to *proc*.

  ```

  ```

## DESCRIPTION

**Tk\_CreateFileHandler** arranges for *proc* to be invoked in the future whenever I/O becomes possible on a file or an exceptional condition exists for the file.  The file is indicated by *id*, and the conditions of interest are indicated by *mask*.  For example, if *mask* is **TK\_READABLE**, *proc* will be called when the file is readable. The callback to *proc* is made by **Tk\_DoOneEvent**, so **Tk\_CreateFileHandler** is only useful in programs that dispatch events through **Tk\_DoOneEvent** or through other Tk procedures that call **Tk\_DoOneEvent**, such as **Tk\_MainLoop**.

*Proc* should have arguments and result that match the type **Tk\_FileProc**:

```
typedef void Tk_FileProc(
ClientData clientData,
int mask);
```

The *clientData* parameter to *proc* is a copy of the *clientData* argument given to **Tk\_CreateFileHandler** when the callback was created.  Typically, *clientData* points to a data structure containing application-specific information about the file.  *Mask* is an integer mask indicating which of the requested conditions actually exists for the file;  it will contain a subset of the bits in the *mask* argument to **Tk\_CreateFileHandler**.

**Tk\_CreateFileHandler2** also creates a file handler, but it provides a lower-level and more flexible interface. The callback procedure *proc2* must have arguments and result that match the following prototype:

```
typedef int Tk_FileProc2(
ClientData clientData,
int mask,
int flags);
```

Whereas a file handler created by **Tk\_CreateFileHandler** is only invoked when the file is known to be \`\`ready'', a file handler created by **Tk\_CreateFileHandler2** is invoked on every pass through the the event loop (**Tk\_DoWhenIdle**); it gets to determine whether the file is \`\`ready'' or not. The *mask* argument contains an OR'ed combination of the bits **TK\_READABLE**, **TK\_WRITABLE**, and **TK\_EXCEPTION**, which indicate whether the file is known to be readable, writable, or to have an exceptional condition present (this is the case if **select** has been invoked since the previous call to *proc2*, and if it indicated that the specified conditions were present). *proc2* may use this information along with additional information of its own, such as knowledge about buffered data, to decide whether the file is really \`\`ready''. The *flags* argument is a copy of the flags passed to **Tk\_DoOneEvent**, which may be used by *proc2* to ignore the file if the appropriate bit, such as **TK\_FILE\_EVENTS**, is not present.

*proc2* must return an integer value that is either **TK\_FILE\_HANDLED** or an OR-ed combination of **TK\_READABLE**, **TK\_WRITABLE**, and **TK\_EXCEPTION**. If the return value is **TK\_FILE\_HANDLED** it means that the file was \`\`ready'' and that *proc2* handled the ready condition; **Tk\_DoOneEvent** will return immediately. If the return value is not **TK\_FILE\_HANDLED**, then it indicates the set of conditions that should be checked for the file if the current invocation of **Tk\_DoWhenIdle** invokes **select**. Typically the return value reflects all of the conditions that *proc2* cares about. A zero return value means that the file should be ignored if **Tk\_DoWhenIdle** calls **select** (this could happen, for example, if the *flags* argument specified that this file's events should be ignored). The value returned by *proc2* only affects a **select** call from the current invocation of **Tk\_DoOneEvent**;  the next invocation of **Tk\_DoOneEvent** will call *proc2* afresh to get new information.

There may exist only one handler for a given file at a given time.  If **Tk\_CreateFileHandler** or **Tk\_CreateFileHandler2** is called when a handler already exists for *id*, then the new callback replaces the information that was previously recorded.

**Tk\_DeleteFileHandler** may be called to delete the file handler for *id*;  if no handler exists for the file given by *id* then the procedure has no effect.

The purpose of file handlers is to enable an application to respond to X events and other events while waiting for files to become ready for I/O.  For this to work correctly, the application may need to use non-blocking I/O operations on the files for which handlers are declared.  Otherwise the application may be put to sleep if it reads or writes too much data; while waiting for the I/O to complete the application won't be able to service other events.  In BSD-based UNIX systems, non-blocking I/O can be specified for a file using the **fcntl** kernel call with the **FNDELAY** flag.

## KEYWORDS

callback, file, handler