Function: read-char

read-char is a function defined in keyboard.c.

Signature

(read-char &optional PROMPT INHERIT-INPUT-METHOD SECONDS)

Documentation

Read a character event from the command input (keyboard or macro).

Return the character as a number. If the event has modifiers, they are resolved and reflected in the returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97). If some of the modifiers cannot be reflected in the character code, the returned value will include those modifiers, and will not be a valid character code: it will fail the characterp test. Use event-basic-type to recover the character code with the modifiers removed.

If the user generates an event which is not a character (i.e. a mouse click or function key event), read-char signals an error. As an exception, switch-frame events are put off until non-character events can be read. If you want to read non-character events, or ignore them, call read-event or read-char-exclusive instead.

If the optional argument PROMPT is non-nil, display that as a prompt. If PROMPT is nil or the string "", the key sequence/events that led to the current command is used as the prompt.

If the optional argument INHERIT-INPUT-METHOD is non-nil and some input method is turned on in the current buffer, that input method is used for reading a character.

If the optional argument SECONDS is non-nil, it should be a number specifying the maximum number of seconds to wait for input. If no input arrives in that time, return nil. SECONDS may be a floating-point value.

If inhibit-interaction is non-nil, this function will signal an inhibited-interaction error.

View in manual

Probably introduced at or before Emacs version 1.12.

Source Code

// Defined in /usr/src/emacs/src/keyboard.c
{
  Lisp_Object val;

  barf_if_interaction_inhibited ();

  if (! NILP (prompt))
    {
      cancel_echoing ();
      message_with_string ("%s", prompt, 0);
    }
  val = read_filtered_event (1, 1, 1, ! NILP (inherit_input_method), seconds);

  return (!FIXNUMP (val) ? Qnil
	  : make_fixnum (char_resolve_modifier_mask (XFIXNUM (val))));
}