---
name: "gicHeadRead"
section: "3"
platform: "linux"
package: "libgiigic1-dev"
version: "1.1.2-2"
release: "Debian 6.0 (Squeeze)"
platforms: ["linux"]
url: "https://new.carta.tech/gicHeadAllocate"
---

# gicHeadRead(3)

Heads

Part of [gicHeadAllocate(3)](/gicHeadAllocate/3.md).

## NAME

**gicHeadAllocate**, **gicHeadFree**, **gicHeadAttachContext**, **gicHeadDetachContext**, **gicHeadLookupContext**, **gicHeadGetContext**, **gicHeadNumContexts**, **gicHeadWrite**, **gicHeadRead**, **gicHeadMapActions** - Heads

## SYNOPSIS

```
#include <ggi/gic.h>
gic_head    *gicHeadAllocate     (gic_handle_t hand,
      char *name);
void         gicHeadFree         (gic_handle_t hand,
      gic_head *head);
int          gicHeadAttachContext(gic_handle_t hand,
      gic_head *head,gic_context *context);
int          gicHeadDetachContext(gic_handle_t hand,
      gic_head *head,gic_context *context);
gic_context *gicHeadLookupContext(gic_handle_t hand,
      gic_head *head,const char *name);
gic_context *gicHeadGetContext   (gic_handle_t hand,
      gic_head *head,int number);
int          gicHeadNumContexts  (gic_handle_t hand,
      gic_head *head);
int          gicHeadWrite        (gic_handle_t hand,
      gic_head *head,FILE *file);
gic_head    *gicHeadRead         (gic_handle_t hand,
      FILE *file);
int          gicHeadMapActions   (gic_handle_t hand,
      gic_head *head,gic_actionlist *actions);
```

## DESCRIPTION

A gic\_head is LIBGIIGIC's notion of a collection of contexts. Each context describes the mappings between inputs and actions for a given situation  in a program.

Thus a head usually describes all the contexts of a program that are managed by libgiigic.

Usually a program will not have to bother with most functions as it will read its config via **gicHeadRead**. However when building apps that  can (re)build the configuration files, the other functions become useful.

A gic\_head is allocated using **gicHeadAllocate**, which takes the gic handle  it will be associated with and a name for the Head. It returns the allocated  head or NULL on failure.

**gicHeadFree** frees an allocated gic\_head.

**gicHeadAttachContext** and **gicHeadDetachContext** are used to attach and detach contexts from a head. A context refers to a situation in a program that has an input mapping attached to it. Most programs will have multiple such contexts, like one for accessing the menus, one for the game mode, etc.

**gicHeadLookupContext** and **gicHeadGetContext** can be used to get access to contexts attached to a head. The former accesses the contexts by name, the latter by number. You can use **gicHeadNumContexts** to query for the number of contexts.

**gicHeadWrite** can be used to write out a textual description of the head. This is usually used to write out a config file after it changed.

**gicHeadRead** will read such a *file*, allocate a gic\_head and fill it with the read data. After that, you should call **gicHeadMapActions** to reestablish the connection between the actions and the action callbacks.

## RETURN VALUE

**gicHeadRead** and **gicHeadAllocate** return the read/allocated head on return or NULL on failure.

**gicHeadAttachContext**, **gicHeadDetachContext**, **gicHeadWrite** and **gicHeadMapActions** return 0 on success and an `gii-error(3)` code on failure.

**gicHeadLookupContext** and **gicHeadGetContext** return the requested context or NULL on failure.

**gicHeadNumContexts** return the number of contexts attached to the head.

## SEE ALSO

TODO