### Example: Interrogating a terminal description with Unix/GNU buffer methods

Source: https://www.gnu.org/software/termutils/manual/termcap-1.3/html_mono/termcap.html

C example showing how to extract capabilities using tgetstr, tgetflag, and tgetnum. It uses a conditional to select between providing a buffer (Unix) or passing a null pointer for malloc allocation (GNU). The example also retrieves the pc, le, and up capabilities for use with tputs and tgoto.

```c
char *tgetstr ();

char *cl_string, *cm_string;
int height;
int width;
int auto_wrap;

char PC;   /* For tputs.  */
char *BC;  /* For tgoto.  */
char *UP;

interrogate_terminal ()
{
#ifdef Unix
  /* Here we assume that an explicit term_buffer
     was provided to tgetent.  */
  char *buffer
    = (char *) malloc (strlen (term_buffer));
#define BUFFADDR &buffer
#else
#define BUFFADDR 0
#endif

  char *temp;

  /* Extract information we will use.  */
  cl_string = tgetstr ("cl", BUFFADDR);
  cm_string = tgetstr ("cm", BUFFADDR);
  auto_wrap = tgetflag ("am");
  height = tgetnum ("li");
  width = tgetnum ("co");

  /* Extract information that termcap functions use.  */
  temp = tgetstr ("pc", BUFFADDR);
  PC = temp ? *temp : 0;
  BC = tgetstr ("le", BUFFADDR);
  UP = tgetstr ("up", BUFFADDR);
}

```

--------------------------------

### Example usage of tgetent with buffer allocation

Source: https://www.gnu.org/software/termutils/manual/termcap-1.3/html_mono/termcap.html

Shows how to call tgetent with a statically allocated buffer on Unix or a null pointer on other systems to let termcap allocate space. It checks the return value and calls fatal on errors. The fatal function is assumed to print an error message and exit.

```c
#ifdef unix
static char term_buffer[2048];
#else
#define term_buffer 0
#endif

init_terminal_data ()
{
  char *termtype = getenv ("TERM");
  int success;

  if (termtype == 0)
    fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");

  success = tgetent (term_buffer, termtype);
  if (success < 0)
    fatal ("Could not access the termcap data base.\n");
  if (success == 0)
    fatal ("Terminal type `%s' is not defined.\n", termtype);
}
```

--------------------------------

### Example of using tparam with tputs

Source: https://www.gnu.org/software/termutils/manual/termcap-1.3/html_mono/termcap.html

Example showing how to call tparam to encode a command into a buffer, output it with tputs, and free the buffer if tparam allocated a new one. If buffer is not big enough, tparam calls malloc; if you pass zero for size and buffer, it always allocates with malloc.

```c
{
char *buf;
char buffer[40];

buf = tparam (command, buffer, 40, parm);
tputs (buf, 1, fputchar);
if (buf != buffer)
free (buf);
}
```

--------------------------------

### tputs

Source: https://www.gnu.org/software/termutils/manual/termcap-1.3/html_mono/termcap.html

Computes and performs padding.

```APIDOC
## tputs

### Description
Computes and performs padding.

### Usage
Call this function to output a string with padding.

### Parameters
- **string** (const char *) - Required - String to output.
- **affcnt** (int) - Required - Number of affected lines.
- **outfun** (int (*)()) - Required - Output function.

### Return Value
Returns an integer.

### Notes
This function is part of the termcap library API.
```

--------------------------------

### tgetstr

Source: https://www.gnu.org/software/termutils/manual/termcap-1.3/html_mono/termcap.html

Interrogates the description for string information.

```APIDOC
## tgetstr

### Description
Interrogates the description for string information.

### Usage
Call this function to retrieve a string capability value.

### Parameters
- **name** (const char *) - Required - Capability name.
- **area** (char **) - Required - Pointer to area for storing the string.

### Return Value
Returns a pointer to the string.

### Notes
This function is part of the termcap library API.
```

--------------------------------

### tgetstr

Source: https://www.gnu.org/software/termutils/manual/termcap-1.3/html_mono/termcap.html

Retrieves a string capability value from the terminal description. Returns a pointer to the string value, or a null pointer if the capability is not present. Supports two methods for providing storage space: automatic allocation via malloc (GNU only) or user-provided buffer space.

```APIDOC
## tgetstr

### Description
Retrieves a string capability value from the terminal description. Returns a pointer to the string value, or a null pointer if the capability is not present. Supports two methods for providing storage space: automatic allocation via malloc (GNU only) or user-provided buffer space.

### Function Signature
```c
char *tgetstr (char *name, char **area);
```

### Parameters
- **name** (char *) - Required - The two-letter code name of the capability.
- **area** (char **) - Required - A pointer to a pointer variable. If null, tgetstr allocates space using malloc (GNU only). If non-null, it should point to a pointer variable that points to available space; tgetstr stores the string there and increments the pointer.

### Return Value
- **char *** - A pointer to the string value, or a null pointer if the capability is not present.

### Notes
- When using the user-provided buffer method, the total size of all string values obtained will not exceed the size of the terminal description buffer.
- The Unix version of termcap only supports the user-provided buffer method.

### Example
```c
char *cl_string = tgetstr ("cl", BUFFADDR);
```
```

--------------------------------

### tgetent

Source: https://www.gnu.org/software/termutils/manual/termcap-1.3/html_mono/termcap.html

Finds the description of the user's terminal type.

```APIDOC
## tgetent

### Description
Finds the description of the user's terminal type.

### Usage
Call this function to retrieve the termcap entry for a given terminal type.

### Parameters
- **bp** (char *) - Required - Buffer to store the termcap entry.
- **name** (const char *) - Required - Terminal type name.

### Return Value
Returns an integer indicating success or failure.

### Notes
This function is part of the termcap library API.
```

--------------------------------

### tgoto

Source: https://www.gnu.org/software/termutils/manual/termcap-1.3/html_mono/termcap.html

Computes the parametrized cursor motion string for the 'cm' capability, with special handling to avoid problematic characters. Returns a pointer to a static buffer that is reused on subsequent calls.

```APIDOC
## tgoto

### Description
Computes the parametrized cursor motion string for the 'cm' capability, with special handling to avoid problematic characters. Returns a pointer to a static buffer that is reused on subsequent calls.

### Function Signature
```c
char *tgoto (char *cstring, int hpos, int vpos)
```

### Parameters
- **cstring** (char *) - Required - The terminal description's 'cm' string.
- **hpos** (int) - Required - The horizontal cursor position.
- **vpos** (int) - Required - The vertical cursor position.

### Return Value
Returns a pointer to an internal static buffer containing the computed parametrized string. The buffer is reused on subsequent calls.

### Notes
- The order of operands is reversed: horizontal position comes before vertical position in the arguments, even though the vertical position comes before horizontal in the 'cm' string parameters.
- For commands other than 'cm' that take one parameter, pass the parameter as the "vertical position".
- The function avoids generating null characters, tabs, and newlines by incrementing the target position and compensating with strings from the global variables `BC` and `UP`.
- If `BC` and `UP` are both zero, the avoidance feature is turned off.
- It is safe to use `tgoto` for commands other than 'cm' only if `BC` and `UP` are zero.

### Global Variables
- **BC** (char *) - External C variable used for moving back one position. Should be set to the 'le' capability string via `tgetstr`.
- **UP** (char *) - External C variable used for moving up one position. Should be set to the 'up' capability string via `tgetstr`.

### Example
```c
char *cm = tgetstr("cm", &buffer);
char *result = tgoto(cm, 10, 5);
```
```

--------------------------------

### tputs

Source: https://www.gnu.org/software/termutils/manual/termcap-1.3/html_mono/termcap.html

Outputs a string containing an optional padding spec, stripping and decoding the padding, outputting the rest of the string, and then outputting the appropriate padding.

```APIDOC
## tputs

### Description
Outputs a string containing an optional padding spec, stripping and decoding the padding, outputting the rest of the string, and then outputting the appropriate padding.

### Function Signature
```c
int tputs (char *string, int nlines, int (*outfun) ());
```

### Parameters
- **string** (char *) - Required - The string (including padding spec) to be output.
- **nlines** (int) - Required - The number of lines affected by the operation, used to multiply the amount of padding if the padding spec ends with a '*'.
- **outfun** (function pointer) - Required - A function (such as `fputchar`) that is called to output each character. When called, it should expect one argument, a character.

### Global Variables
- **ospeed** (short) - Required - The terminal output speed, encoded as in the `ioctl` system call. Used to compute the number of padding characters.
- **PC** (char) - Required - The character used for padding. Should be taken from the 'pc' capability in the terminal description, or zero if there is no 'pc' capability.

### Usage Notes
- The caller is responsible for storing suitable values into `ospeed` and `PC` before using `tputs`.
- The value of `nlines` should be the number of lines whose contents will be cleared or moved by the command.
  - For cursor motion commands or commands that do editing within one line, use 1.
  - For most commands that affect multiple lines (e.g., 'al', 'cd'), use the screen height minus the current vertical position (origin 0).
  - For multiple insert and scroll commands (e.g., 'AL'), use the same value as above; the number of lines being inserted is not correct.
  - If a scroll window feature is used, adjust `nlines` to account for the reduced number of lines affected.
  - For 'ic' and 'dc' commands, `nlines` should always be 1, even though padding is proportional to the number of characters affected.

### Return Value
- (int) - The function returns an integer (exact return value not specified in the source).
```

--------------------------------

### tgetflag

Source: https://www.gnu.org/software/termutils/manual/termcap-1.3/html_mono/termcap.html

Retrieves a boolean capability value from the terminal description. Returns 1 if the capability is present, or 0 if it is not.

```APIDOC
## tgetflag

### Description
Retrieves a boolean capability value from the terminal description. Returns 1 if the capability is present, or 0 if it is not.

### Function Signature
```c
int tgetflag (char *name);
```

### Parameters
- **name** (char *) - Required - The two-letter code name of the capability.

### Return Value
- **int** - 1 if the capability is present in the terminal description, 0 otherwise.

### Example
```c
int auto_wrap = tgetflag ("am");
```
```

--------------------------------

### tgetent

Source: https://www.gnu.org/software/termutils/manual/termcap-1.3/html_mono/termcap.html

Looks up the terminal description for a given terminal type and stores it internally for later interrogation. Returns -1 on database access error, 0 if the type is not defined, and a positive value on success.

```APIDOC
## tgetent

### Description
Looks up the terminal description for the specified terminal type and stores it internally for later interrogation with tgetnum, tgetstr, or tgetflag.

### Function Signature
int tgetent (char *buffer, char *termtype);

### Parameters
- **buffer** (char *) - Optional - Pointer to a buffer where the description will be stored. If NULL, the GNU version of termcap allocates space using malloc. For Unix version, must point to a buffer of at least 2048 characters.
- **termtype** (char *) - Required - String containing the terminal type name, typically obtained from the environment variable TERM.

### Return Value
- **-1** - Difficulty accessing the termcap database.
- **0** - Database accessible but the specified terminal type is not defined.
- **Other** - Success; the description has been stored.

### Usage Notes
- The TERMCAP environment variable overrides the database. If its value starts with '/', it is treated as a file name; otherwise, it is used as the terminal description itself.
- The buffer contents must remain unchanged while the description is being interrogated.

### Example
```c
#ifdef unix
static char term_buffer[2048];
#else
#define term_buffer 0
#endif

init_terminal_data ()
{
  char *termtype = getenv ("TERM");
  int success;

  if (termtype == 0)
    fatal ("Specify a terminal type with `setenv TERM <yourtype>'.\n");

  success = tgetent (term_buffer, termtype);
  if (success < 0)
    fatal ("Could not access the termcap data base.\n");
  if (success == 0)
    fatal ("Terminal type `%s' is not defined.\n", termtype);
}
```
```

--------------------------------

### tgetnum

Source: https://www.gnu.org/software/termutils/manual/termcap-1.3/html_mono/termcap.html

Retrieves a numeric capability value from the terminal description. Returns the nonnegative numeric value if the capability is present, or -1 if it is not mentioned.

```APIDOC
## tgetnum

### Description
Retrieves a numeric capability value from the terminal description. Returns the nonnegative numeric value if the capability is present, or -1 if it is not mentioned.

### Function Signature
```c
int tgetnum (char *name);
```

### Parameters
- **name** (char *) - Required - The two-letter code name of the capability.

### Return Value
- **int** - The numeric value of the capability if present (nonnegative), or -1 if the capability is not mentioned in the terminal description.

### Example
```c
int width = tgetnum ("co");
```
```