---
name: "GetFile"
section: "3tcl"
platform: "linux"
package: "tcl7.6-dev"
version: "7.6p2-7"
release: "Debian 2.1 (Slink)"
platforms: ["linux"]
url: "https://new.carta.tech/GetFile"
---

# GetFile(3tcl)

procedures to manipulate generic file handles

```

```

## NAME

Tcl\_GetFile, Tcl\_FreeFile, Tcl\_GetFileInfo - procedures to manipulate generic file handles

## SYNOPSIS

```
#include <tcl.h>

Tcl_File
Tcl_GetFile(osHandle, type)

Tcl_FreeFile(handle)

ClientData
Tcl_GetFileInfo(handle, typePtr)

ClientData
Tcl_GetNotifierData(handle, freeProcPtr)

Tcl_SetNotifierData(handle, freeProc, clientData)
```

## ARGUMENTS

- ClientData *osHandle* (in)

  Platform-specific file handle to be associated with the generic file handle.

- int *type* (in)

  The type of platform-specific file handle associated with the generic file handle.  See below for a list of valid types.

- Tcl\_File *handle* (in)

  Generic file handle associated with platform-specific file information.

- int *\*typePtr* (in/out)

  If *\*typePtr* is not NULL, then the specified word is set to contain the type associated with *handle*.

- Tcl\_FileFreeProc *\*freeProc* (in)

  Procedure to call when *handle* is deleted.

- Tcl\_FileFreeProc *\*\*freeProcPtr* (in/out)

  Pointer to location in which to store address of current free procedure for file handle.  Ignored if NULL.

- ClientData *clientData* (in)

  Arbitrary one-word value associated with the given file handle. This data is owned by the caller.

  ```

  ```

## DESCRIPTION

A **Tcl\_File** is an opaque handle used to refer to files in a platform independent way in Tcl routines like **Tcl\_CreateFileHandler**.  A file handle has an associated platform-dependent *osHandle*, a *type* and additional private data used by the notifier to generate events for the file.  The type is an integer that determines how the platform-specific drivers will interpret the *osHandle*.  The types that are defined by the core are:

- **TCL\_UNIX\_FD**

  The *osHandle* is a Unix file descriptor.

- **TCL\_MAC\_FILE**

  The file is a Macintosh file handle.

- **TCL\_WIN\_FILE**

  The *osHandle* is a Windows normal file **HANDLE**.

- **TCL\_WIN\_PIPE**

  The *osHandle* is a Windows anonymous pipe **HANDLE**.

- **TCL\_WIN\_SOCKET**

  The *osHandle* is a Windows **SOCKET**.

- **TCL\_WIN\_CONSOLE**

  The *osHandle* is a Windows console buffer **HANDLE**.

**Tcl\_GetFile** locates the file handle corresponding to a particular *osHandle* and a *type*.  If a file handle already existed for the given file, then that handle will be returned.  If this is the first time that the file handle for a particular file is being retrieved, then a new file handle will be allocated and returned.

When a file handle is no longer in use, it should be deallocated with a call to **Tcl\_FreeFile**.  A call to this function will invoke the notifier free procedure *proc*, if there is one.  After the notifier has cleaned up, any resources used by the file handle will be deallocated.  **Tcl\_FreeFile** will not close the platform-specific *osHandle*.

**Tcl\_GetFileInfo** may be used to retrieve the platform-specific *osHandle* and type associated with a file handle.  If *typePtr* is not NULL, then the word at *\*typePtr* is set to the type of the file handle.  The return value of the function is the associated platform-specific *osHandle*.  Note that this function may be used to extract the platform-specific file handle from a **Tcl\_File** so that it may be used in external interfaces. However, programs written using this interface will be platform-specific.

The **Tcl\_SetNotifierData** and **Tcl\_GetNotifierData** procedures are intended to be used only by notifier writers.  See the *[Tcl\_CreateEventSource(3)](/Tcl_CreateEventSource/3.md)* manual entry for more information on the notifier.

**Tcl\_SetNotifierData** may be used by notifier writers to associate notifier-specific information with a **Tcl\_File**.  The *data* argument specifies a word that may be retrieved with a later call to **Tcl\_GetNotifierData**.  If the *freeProc* argument is non-NULL it specifies the address of a procedure to invoke when the **Tcl\_File** is deleted.  *freeProc* should have arguments and result that match the type **Tcl\_FileFreeProc**:

```
typedef void Tcl_FileFreeProc(
	ClientData clientData);
```

When *freeProc* is invoked the *clientData* argument will be the same as the corresponding argument passed to **Tcl\_SetNotifierData**.

**Tcl\_GetNotifierData** returns the *clientData* associated with the given **Tcl\_File**, and if the *freeProcPtr* field is non-**NULL**, the address indicated by it gets the address of the free procedure stored with this file.

## KEYWORDS

generic file handle, file type, file descriptor, notifier