tcinject()

Updated: April 19, 2023

Inject characters into a device's input buffer

Synopsis:

#include <termios.h>

int tcinject( int filedes, 
              char *buf, 
              int n );

Arguments:

filedes
A file descriptor that's associated with the device whose input buffer you want to add characters to.
buf
A pointer to a buffer that contains the characters that you want to insert.
n
The number of characters to insert. If n is positive, the characters are written to the canonical (edited) queue. If n is negative, the characters are written to the raw queue.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The tcinject() function injects n characters pointed to by buf into the input buffer of the device given in filedes.

Note that while injecting into the canonical queue, editing characters in buf are acted upon as though the user entered them directly from the device. If buf doesn't contain a newline (‘\n’), carriage return (‘\r’) or a data-forwarding character such as an EOF, data doesn't become available for reading. If buf does contain a data-forwarding character, it should contain only one as the last character in buf.

This function is useful for implementing command-line recall algorithms by injecting recalled lines into the canonical queue.

Returns:

0
Success.
-1
An error occurred (errno is set).

Errors:

EBADF
The filedes argument is invalid or the file isn't opened for reading.
EINTR
The call was interrupted by a signal.
ENOTTY
The argument filedes doesn't refer to a terminal device.

Examples:

#include <stdio.h>
#include <stdlib.h>
#include <termios.h>

int main( void )
{
  char *p = "echo Hello world!\n";

  /* Inject the line all at once */
  tcinject(0, p, strlen(p));

  /* Inject the line one character at a time */
  while(*p)
    tcinject(0, p++, 1);
  return EXIT_SUCCESS;
}

Classification:

QNX Neutrino

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes