---
name: "el_getc"
section: "3el"
platform: "linux"
package: "libedit-dev"
version: "2.11-20080614-5"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/editline/3el"
---

# el\_getc(3el)

line editor, history and tokenization functions

Part of [editline(3el)](/editline/3el.md).

## NAME

**editline**, **el\_init**, **el\_end**, **el\_reset**, **el\_gets**, **el\_getc**, **el\_push**, **el\_parse**, **el\_set**, **el\_get**, **el\_source**, **el\_resize**, **el\_line**, **el\_insertstr**, **el\_deletestr**, **history\_init**, **history\_end**, **history**, **tok\_init**, **tok\_end**, **tok\_reset**, **tok\_line**, **tok\_str** – line editor, history and tokenization functions

## LIBRARY

library “libedit”

## SYNOPSIS

**#include \<histedit.h\>**

*EditLine* *\**\

**el\_init**(*const char \*prog*, *FILE \*fin*, *FILE \*fout*, *FILE \*ferr*);

*void*\

**el\_end**(*EditLine \*e*);

*void*\

**el\_reset**(*EditLine \*e*);

*const* *char* *\**\

**el\_gets**(*EditLine \*e*, *int \*count*);

*int*\

**el\_getc**(*EditLine \*e*, *char \*ch*);

*void*\

**el\_push**(*EditLine \*e*, *const char \*str*);

*int*\

**el\_parse**(*EditLine \*e*, *int argc*, *const char \*argv\[\]*);

*int*\

**el\_set**(*EditLine \*e*, *int op*, *...*);

*int*\

**el\_get**(*EditLine \*e*, *int op*, *...*);

*int*\

**el\_source**(*EditLine \*e*, *const char \*file*);

*void*\

**el\_resize**(*EditLine \*e*);

*const* *LineInfo* *\**\

**el\_line**(*EditLine \*e*);

*int*\

**el\_insertstr**(*EditLine \*e*, *const char \*str*);

*void*\

**el\_deletestr**(*EditLine \*e*, *int count*);

*History* *\**\

**history\_init**();

*void*\

**history\_end**(*History \*h*);

*int*\

**history**(*History \*h*, *HistEvent \*ev*, *int op*, *...*);

*Tokenizer* *\**\

**tok\_init**(*const char \*IFS*);

*void*\

**tok\_end**(*Tokenizer \*t*);

*void*\

**tok\_reset**(*Tokenizer \*t*);

*int*\

**tok\_line**(*Tokenizer \*t*, *const LineInfo \*li*, *int \*argc*, *const char \*\*argv\[\]*, *int \*cursorc*, *int \*cursoro*);

*int*\

**tok\_str**(*Tokenizer \*t*, *const char \*str*, *int \*argc*, *const char \*\*argv\[\]*);

## DESCRIPTION

The **editline** library provides generic line editing, history and tokenization functions, similar to those found in [sh(1)](/sh/1.md).

These functions are available in the **libedit** library (which needs the **libtermcap** library). Programs should be linked with **-ledit** **-ltermcap**.

## LINE EDITING FUNCTIONS

The line editing functions use a common data structure, *EditLine*, which is created by **el\_init**() and freed by **el\_end**().

The following functions are available:

- **el\_init**()

  Initialise the line editor, and return a data structure to be used by all other line editing functions. *prog* is the name of the invoking program, used when reading the [editrc(5)](/editrc/5.md) file to determine which settings to use. *fin*, *fout* and *ferr* are the input, output, and error streams (respectively) to use. In this documentation, references to “the tty” are actually to this input/output stream combination.

- **el\_end**()

  Clean up and finish with *e*, assumed to have been created with **el\_init**().

- **el\_reset**()

  Reset the tty and the parser. This should be called after an error which may have upset the tty's state.

- **el\_gets**()

  Read a line from the tty. *count* is modified to contain the number of characters read. Returns the line read if successful, or NULL if no characters were read or if an error occurred.

- **el\_getc**()

  Read a character from the tty. *ch* is modified to contain the character read. Returns the number of characters read if successful, -1 otherwise.

- **el\_push**()

  Pushes *str* back onto the input stream. This is used by the macro expansion mechanism. Refer to the description of **bind** **-s** in [editrc(5)](/editrc/5.md) for more information.

- **el\_parse**()

  Parses the *argv* array (which is *argc* elements in size) to execute builtin **editline** commands. If the command is prefixed with “prog”: then **el\_parse**() will only execute the command if “prog” matches the *prog* argument supplied to **el\_init**(). The return value is -1 if the command is unknown, 0 if there was no error or “prog” didn't match, or 1 if the command returned an error. Refer to [editrc(5)](/editrc/5.md) for more information.

- **el\_set**()

  Set **editline** parameters. *op* determines which parameter to set, and each operation has its own parameter list.

  The following values for *op* are supported, along with the required argument list:

  - EL\_PROMPT, *char \*(\*f)(EditLine \*)*

    Define prompt printing function as *f*, which is to return a string that contains the prompt.

  - EL\_REFRESH

    Re-display the current line on the next terminal line.

  - EL\_RPROMPT, *char \*(\*f)(EditLine \*)*

    Define right side prompt printing function as *f*, which is to return a string that contains the prompt.

  - EL\_TERMINAL, *const char \*type*

    Define terminal type of the tty to be *type*, or to TERM if *type* is NULL.

  - EL\_EDITOR, *const char \*mode*

    Set editing mode to *mode*, which must be one of “emacs” or “vi”.

  - EL\_SIGNAL, *int flag*

    If *flag* is non-zero, **editline** will install its own signal handler for the following signals when reading command input: SIGCONT, SIGHUP, SIGINT, SIGQUIT, SIGSTOP, SIGTERM, SIGTSTP, and SIGWINCH. Otherwise, the current signal handlers will be used.

  - EL\_BIND,

    *const char \**, *...*, NULL Perform the **bind** builtin command. Refer to [editrc(5)](/editrc/5.md) for more information.

  - EL\_ECHOTC,

    *const char \**, *...*, NULL Perform the **echotc** builtin command. Refer to [editrc(5)](/editrc/5.md) for more information.

  - EL\_SETTC,

    *const char \**, *...*, NULL Perform the **settc** builtin command. Refer to [editrc(5)](/editrc/5.md) for more information.

  - EL\_SETTY,

    *const char \**, *...*, NULL Perform the **setty** builtin command. Refer to [editrc(5)](/editrc/5.md) for more information.

  - EL\_TELLTC,

    *const char \**, *...*, NULL Perform the **telltc** builtin command. Refer to [editrc(5)](/editrc/5.md) for more information.

  - EL\_ADDFN,

    *const char \*name*, *const char \*help*, *unsigned char (\*func)(EditLine \*e, int ch)* Add a user defined function, **func**(), referred to as *name* which is invoked when a key which is bound to *name* is entered. *help* is a description of *name*. At invocation time, *ch* is the key which caused the invocation. The return value of **func**() should be one of:

    - CC\_NORM

      Add a normal character.

    - CC\_NEWLINE

      End of line was entered.

    - CC\_EOF

      EOF was entered.

    - CC\_ARGHACK

      Expecting further command input as arguments, do nothing visually.

    - CC\_REFRESH

      Refresh display.

    - CC\_REFRESH\_BEEP

      Refresh display, and beep.

    - CC\_CURSOR

      Cursor moved, so update and perform CC\_REFRESH.

    - CC\_REDISPLAY

      Redisplay entire input line. This is useful if a key binding outputs extra information.

    - CC\_ERROR

      An error occurred. Beep, and flush tty.

    - CC\_FATAL

      Fatal error, reset tty to known state.

  - EL\_HIST,

    *History \*(\*func)(History \*, int op, ...)*, *const char \*ptr* Defines which history function to use, which is usually **history**(). *ptr* should be the value returned by **history\_init**().

  - EL\_EDITMODE, *int flag*

    If *flag* is non-zero, editing is enabled (the default). Note that this is only an indication, and does not affect the operation of **editline**. At this time, it is the caller's responsibility to check this (using **el\_get**()) to determine if editing should be enabled or not.

  - EL\_GETCFN, *int (\*f)(EditLine \*, char \*c)*

    Define the character reading function as *f*, which is to return the number of characters read and store them in *c*. This function is called internally by **el\_gets**() and **el\_getc**(). The builtin function can be set or restored with the special function name \`\`EL\_BUILTIN\_GETCFN''.

  - EL\_CLIENTDATA, *void \*data*

    Register *data* to be associated with this EditLine structure. It can be retrieved with the corresponding **el\_get**() call.

  - EL\_SETFP, *int fd*, *FILE \*fp*

    Set the current **editline** file pointer for “input” *fd* = 0, “output” *fd* = 1, or “error” *fd* = 2 from *fp*.

- **el\_get**()

  Get **editline** parameters. *op* determines which parameter to retrieve into *result*. Returns 0 if successful, -1 otherwise.

  The following values for *op* are supported, along with actual type of *result*:

  - EL\_PROMPT, *char \*(\*f)(EditLine \*)*

    Return a pointer to the function that displays the prompt.

  - EL\_RPROMPT, *char \*(\*f)(EditLine \*)*

    Return a pointer to the function that displays the rightside prompt.

  - EL\_EDITOR, *const char \**

    Return the name of the editor, which will be one of “emacs” or “vi”.

  - EL\_GETTC, *const char \*name*, *void \*value*

    Return non-zero if *name* is a valid [termcap(5)](/termcap/5.md) capability and set *value* to the current value of that capability.

  - EL\_SIGNAL, *int \**

    Return non-zero if **editline** has installed private signal handlers (see **el\_get**() above).

  - EL\_EDITMODE, *int \**

    Return non-zero if editing is enabled.

  - EL\_GETCFN, *int (\*\*f)(EditLine \*, char \*)*

    Return a pointer to the function that read characters, which is equal to \`\`EL\_BUILTIN\_GETCFN'' in the case of the default builtin function.

  - EL\_CLIENTDATA, *void \*\*data*

    Retrieve *data* previously registered with the corresponding **el\_set**() call.

  - EL\_UNBUFFERED, *int*

    Sets or clears unbuffered mode. In this mode, **el\_gets**() will return immediately after processing a single character.

  - EL\_PREP\_TERM, *int*

    Sets or clears terminal editing mode.

  - EL\_GETFP, *int fd*, *FILE \*\*fp*

    Return in *fp* the current **editline** file pointer for “input” *fd* = 0, “output” *fd* = 1, or “error” *fd* = 2.

- **el\_source**()

  Initialise **editline** by reading the contents of *file*. **el\_parse**() is called for each line in *file*. If *file* is NULL, try *$PWD/.editrc* then *$HOME/.editrc*. Refer to [editrc(5)](/editrc/5.md) for details on the format of *file*.

- **el\_resize**()

  Must be called if the terminal size changes. If EL\_SIGNAL has been set with **el\_set**(), then this is done automatically. Otherwise, it's the responsibility of the application to call **el\_resize**() on the appropriate occasions.

- **el\_line**()

  Return the editing information for the current line in a *LineInfo* structure, which is defined as follows:

  ```
  typedef struct lineinfo {
      const char *buffer;    /* address of buffer */
      const char *cursor;    /* address of cursor */
      const char *lastchar;  /* address of last character */
  } LineInfo;
  ```

  *buffer* is not NUL terminated. This function may be called after **el\_gets**() to obtain the *LineInfo* structure pertaining to line returned by that function, and from within user defined functions added with EL\_ADDFN.

- **el\_insertstr**()

  Insert *str* into the line at the cursor. Returns -1 if *str* is empty or won't fit, and 0 otherwise.

- **el\_deletestr**()

  Delete *count* characters before the cursor.

## HISTORY LIST FUNCTIONS

The history functions use a common data structure, *History*, which is created by **history\_init**() and freed by **history\_end**().

The following functions are available:

- **history\_init**()

  Initialise the history list, and return a data structure to be used by all other history list functions.

- **history\_end**()

  Clean up and finish with *h*, assumed to have been created with **history\_init**().

- **history**()

  Perform operation *op* on the history list, with optional arguments as needed by the operation. *ev* is changed accordingly to operation. The following values for *op* are supported, along with the required argument list:

  - H\_SETSIZE, *int size*

    Set size of history to *size* elements.

  - H\_GETSIZE

    Get number of events currently in history.

  - H\_END

    Cleans up and finishes with *h*, assumed to be created with **history\_init**().

  - H\_CLEAR

    Clear the history.

  - H\_FUNC,

    *void \*ptr*, *history\_gfun\_t first*, *history\_gfun\_t next*, *history\_gfun\_t last*, *history\_gfun\_t prev*, *history\_gfun\_t curr*, *history\_sfun\_t set*, *history\_vfun\_t clear*, *history\_efun\_t enter*, *history\_efun\_t add* Define functions to perform various history operations. *ptr* is the argument given to a function when it's invoked.

  - H\_FIRST

    Return the first element in the history.

  - H\_LAST

    Return the last element in the history.

  - H\_PREV

    Return the previous element in the history.

  - H\_NEXT

    Return the next element in the history.

  - H\_CURR

    Return the current element in the history.

  - H\_SET

    Set the cursor to point to the requested element.

  - H\_ADD, *const char \*str*

    Append *str* to the current element of the history, or perform the H\_ENTER operation with argument *str* if there is no current element.

  - H\_APPEND, *const char \*str*

    Append *str* to the last new element of the history.

  - H\_ENTER, *const char \*str*

    Add *str* as a new element to the history, and, if necessary, removing the oldest entry to keep the list to the created size. If H\_SETUNIQUE was has been called with a non-zero arguments, the element will not be entered into the history if its contents match the ones of the current history element. If the element is entered **history**() returns 1, if it is ignored as a duplicate returns 0. Finally **history**() returns -1 if an error occurred.

  - H\_PREV\_STR, *const char \*str*

    Return the closest previous event that starts with *str*.

  - H\_NEXT\_STR, *const char \*str*

    Return the closest next event that starts with *str*.

  - H\_PREV\_EVENT, *int e*

    Return the previous event numbered *e*.

  - H\_NEXT\_EVENT, *int e*

    Return the next event numbered *e*.

  - H\_LOAD, *const char \*file*

    Load the history list stored in *file*.

  - H\_SAVE, *const char \*file*

    Save the history list to *file*.

  - H\_SETUNIQUE, *int unique*

    Set flag that adjacent identical event strings should not be entered into the history.

  - H\_GETUNIQUE

    Retrieve the current setting if adjacent identical elements should be entered into the history.

  - H\_DEL, *int e*

    Delete the event numbered *e*. This function is only provided for [readline(3)](/readline/3.md) compatibility. The caller is responsible for free'ing the string in the returned *HistEvent*.

    **history**() returns = 0 if the operation *op* succeeds. Otherwise, -1 is returned and *ev* is updated to contain more details about the error.

## TOKENIZATION FUNCTIONS

The tokenization functions use a common data structure, *Tokenizer*, which is created by **tok\_init**() and freed by **tok\_end**().

The following functions are available:

- **tok\_init**()

  Initialise the tokenizer, and return a data structure to be used by all other tokenizer functions. *IFS* contains the Input Field Separators, which defaults to ⟨space⟩, ⟨tab⟩, and ⟨newline⟩ if NULL.

- **tok\_end**()

  Clean up and finish with *t*, assumed to have been created with **tok\_init**().

- **tok\_reset**()

  Reset the tokenizer state. Use after a line has been successfully tokenized by **tok\_line**() or **tok\_str**() and before a new line is to be tokenized.

- **tok\_line**()

  Tokenize *li*, If successful, modify: *argv* to contain the words, *argc* to contain the number of words, *cursorc* (if not NULL) to contain the index of the word containing the cursor, and *cursoro* (if not NULL) to contain the offset within *argv\[cursorc\]* of the cursor.

  Returns 0 if successful, -1 for an internal error, 1 for an unmatched single quote, 2 for an unmatched double quote, and 3 for a backslash quoted ⟨newline⟩. A positive exit code indicates that another line should be read and tokenization attempted again.

- **tok\_str**()

  A simpler form of **tok\_line**(); *str* is a NUL terminated string to tokenize.

## SEE ALSO

[sh(1)](/sh/1.md), [signal(3)](/signal/3.md), [termcap(3)](/termcap/3.md), [editrc(5)](/editrc/5.md), [termcap(5)](/termcap/5.md)

## HISTORY

The **editline** library first appeared in 4.4BSD. CC\_REDISPLAY appeared in NetBSD 1.3. CC\_REFRESH\_BEEP, EL\_EDITMODE and the readline emulation appeared in NetBSD 1.4. EL\_RPROMPT appeared in NetBSD 1.5.

## AUTHORS

The **editline** library was written by Christos Zoulas. Luke Mewburn wrote this manual and implemented CC\_REDISPLAY, CC\_REFRESH\_BEEP, EL\_EDITMODE, and EL\_RPROMPT. Jaromir Dolecek implemented the readline emulation.

## BUGS

At this time, it is the responsibility of the caller to check the result of the EL\_EDITMODE operation of **el\_get**() (after an **el\_source**() or **el\_parse**()) to determine if **editline** should be used for further input. I.e., EL\_EDITMODE is purely an indication of the result of the most recent [editrc(5)](/editrc/5.md) **edit** command.