ncpty

An NCurses pseudoterminal library.

API still under initial development.

API

struct ncpty_t

Public Members

int fd

File descriptor for master-side of pseudoterminal.

pid_t pid

Process id.

VTerm *vt

Virtual terminal pointer.

PANEL *panel

ncurses panel

file ncpty.h

#include <ncurses.h>

#include <panel.h>

#include <sys/types.h>

#include <vterm.h>

Public header for ncpty - the curses pseudoterminal.

Typedefs

typedef struct ncpty_t ncpty

Functions

struct ncpty_t *ncpty_new(PANEL *panel)

Allocate a new ncpty object assigned with an ncurses PANEL.

The pseudoterminal assumes responsibility for the WINDOW until a call to ncpty_free and any existing pointers to the WINDOW should be considered invalid.

Parameters:

panel – [in] ncurses panel to be used by the pseudoterminal process

Returns:

a newly allocated ncpty_t if successful, otherwise returns NULL

void ncpty_free(struct ncpty_t *pty)

Deallocate an ncpty object.

Parameters:

pty – [in] ncpty object to destroy

int ncpty_execvp(struct ncpty_t *pty, const char *file, char *const argv[])

Create a pseudoterminal, fork, exec and attach a child process to the child-side.

If this call fails for any reason, the ncpty object is left in a definite state.

Parameters:

• pty – [out] ncpty object device

• file – [in] filename of file to executed (will search on $PATH)

• argv – [in] array of null-terminated string arguments, terminated by a null pointer

Returns:

0 for success, -1 for execvp error. errno is set to indicate the specific error encountered.

bool ncpty_status(struct ncpty_t *pty, int *exit_code)

Check if child process controlled by ncpty object has exited.

Parameters:

• pty – [in] ncpty object

• exit_code – [out]

Returns:

true if process is still running, false otherwise

void ncpty_exit(int exit_code)

Exit program.

Convenience function. Uses exit_curses if built with ncurses 6.2.20191214 or later.

Parameters:

exit_code – [in]

file banner.c

#include <stdio.h>

#include <string.h>

#include <sys/stat.h>

#include <sys/types.h>

#include <sys/wait.h>

#include <unistd.h>

#include “ncpty.h”

Simple example of ncpty use that wraps a terminal in header and footer banners.

Functions

void print_usage(const char *name)

int fallback(int argc, char **argv)

int main(int argc, char **argv)

file ncpty.c

#include “ncpty.h”

#include <curses.h>

#include <fcntl.h>

#include <stdio.h>

#include <stdlib.h>

#include <string.h>

#include <sys/ioctl.h>

#include <sys/wait.h>

#include <termios.h>

#include <unistd.h>

Functions

struct ncpty_t *ncpty_new(PANEL *panel)

Allocate a new ncpty object assigned with an ncurses PANEL.

The pseudoterminal assumes responsibility for the WINDOW until a call to ncpty_free and any existing pointers to the WINDOW should be considered invalid.

Parameters:

panel – [in] ncurses panel to be used by the pseudoterminal process

Returns:

a newly allocated ncpty_t if successful, otherwise returns NULL

void ncpty_free(struct ncpty_t *pty)

Deallocate an ncpty object.

Parameters:

pty – [in] ncpty object to destroy

int ncpty_execvp(struct ncpty_t *pty, const char *file, char *const argv[])

Create a pseudoterminal, fork, exec and attach a child process to the child-side.

If this call fails for any reason, the ncpty object is left in a definite state.

Parameters:

• pty – [out] ncpty object device

• file – [in] filename of file to executed (will search on $PATH)

• argv – [in] array of null-terminated string arguments, terminated by a null pointer

Returns:

0 for success, -1 for execvp error. errno is set to indicate the specific error encountered.

bool ncpty_status(struct ncpty_t *pty, int *exit_code)

Check if child process controlled by ncpty object has exited.

Parameters:

• pty – [in] ncpty object

• exit_code – [out]

Returns:

true if process is still running, false otherwise

void ncpty_exit(int exit_code)

Exit program.

Convenience function. Uses exit_curses if built with ncurses 6.2.20191214 or later.

Parameters:

exit_code – [in]

file ncpty_test.c

#include “greatest.h”

#include “ncpty.h”

#include <sys/resource.h>

#include <sys/queue.h>

#include <sys/time.h>

Functions

TEST invalid_status_tests(void)

TEST invalid_free_test(void)

TEST fork_fail_test(void)

TEST resource_starvation_test(void)

GREATEST_MAIN_DEFS()

int main(int argc, char **argv)

dir src/bin

dir include

dir src/lib

dir src

dir src/test