.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "notcurses_fds" "3" "v2.0.4" "" ""
.hy
.SH NAME
.PP
notcurses_fds - dumping file descriptors and subprocesses to planes
.SH SYNOPSIS
.PP
\f[B]#include <notcurses/notcurses.h>\f[R]
.IP
.nf
\f[C]
struct ncplane;
struct ncfdplane;
struct ncsubproc;

typedef struct ncfdplane_options {
  void* curry; // parameter provided to callbacks
  bool follow; // keep reading after hitting end?
} ncfdplane_options;

typedef struct ncsubproc_options {
  void* curry; // parameter provided to callbacks
  uint64_t restart_period;  // restart after exit
} ncsubproc_options;
\f[R]
.fi
.PP
\f[B]typedef int(\f[BI]ncfdplane_callback)(struct ncfdplane\f[B]
\f[R]\f[I]n\f[R]\f[B], const void* \f[R]\f[I]buf\f[R]\f[B], size_t
\f[R]\f[I]s\f[R]\f[B], void* \f[R]\f[I]curry\f[R]\f[B]);\f[R]
.PP
\f[B]typedef int(\f[BI]ncfdplane_done_cb)(struct ncfdplane\f[B]
\f[R]\f[I]n\f[R]\f[B], int \f[R]\f[I]fderrno\f[R]\f[B], void*
\f[R]\f[I]curry\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncfdplane* ncfdplane_create(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const ncfdplane_options*
\f[R]\f[I]opts\f[R]\f[B], int \f[R]\f[I]fd\f[R]\f[B], ncfdplane_callback
\f[R]\f[I]cbfxn\f[R]\f[B], ncfdplane_done_cb
\f[R]\f[I]donecbfxn\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* ncfdplane_plane(struct ncfdplane*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncfdplane_destroy(struct ncfdplane*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncsubproc* ncsubproc_createv(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const ncsubproc_options*
\f[R]\f[I]opts\f[R]\f[B], const char* \f[R]\f[I]bin\f[R]\f[B], char*
const \f[R]\f[I]arg\f[R]\f[B][], ncfdplane_callback
\f[R]\f[I]cbfxn\f[R]\f[B], ncfdplane_done_cb
\f[R]\f[I]donecbfxn\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncsubproc* ncsubproc_createvp(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const ncsubproc_options*
\f[R]\f[I]opts\f[R]\f[B], const char* \f[R]\f[I]bin\f[R]\f[B], char*
const \f[R]\f[I]arg\f[R]\f[B][], ncfdplane_callback
\f[R]\f[I]cbfxn\f[R]\f[B], ncfdplane_done_cb
\f[R]\f[I]donecbfxn\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncsubproc* ncsubproc_createvpe(struct ncplane*
\f[R]\f[I]n\f[R]\f[B], const ncsubproc_options*
\f[R]\f[I]opts\f[R]\f[B], const char* \f[R]\f[I]bin\f[R]\f[B], char*
const \f[R]\f[I]arg\f[R]\f[B][], char* const \f[R]\f[I]env\f[R]\f[B][],
ncfdplane_callback \f[R]\f[I]cbfxn\f[R]\f[B], ncfdplane_done_cb
\f[R]\f[I]donecbfxn\f[R]\f[B]);\f[R]
.PP
\f[B]struct ncplane* ncsubproc_plane(struct ncsubproc*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.PP
\f[B]int ncsubproc_destroy(struct ncsubproc*
\f[R]\f[I]n\f[R]\f[B]);\f[R]
.SH DESCRIPTION
.PP
These widgets cause a file descriptor to be read until EOF, and written
to a scrolling \f[B]ncplane\f[R].
The reading will take place in a notcurses-managed context (the
particulars of this context are not defined, and should not be depended
upon), which will invoke the provided callbacks with the data read.
Essentially, they are simply portable interfaces to asynchronous
reading, with \f[B]ncsubproc\f[R] also providing subprocess management.
.PP
If \f[B]ncsubproc_destroy\f[R] is called before the subprocess has
exited, it will be sent a SIGKILL.
If \f[B]ncsubproc_destroy\f[R] or \f[B]ncfdplane_destroy\f[R] is called
while a callback is being invoked, the destroy function will block until
the callback is done being invoked.
If a user callback returns non-0, the calling object will destroy
itself.
If a user callback calls the relevant destroy function itself, the
thread will exit as if non-0 had been returned, and the
\f[B]ncsubproc\f[R]\[cq]s resources will at that time be reclaimed.
.PP
It is essential that the destroy function be called once and only once,
whether it is from within the thread\[cq]s context, or external to that
context.
.SH NOTES
.PP
\f[B]ncsubproc\f[R] makes use of pidfds and
\f[B]pidfd_send_signal(2)\f[R], and thus makes reliable use of signals
(it will never target a process other than the true subprocess).
.SH RETURN VALUES
.SH SEE ALSO
.PP
\f[B]pidfd_open(2)\f[R], \f[B]notcurses(3)\f[R],
\f[B]notcurses_plane(3)\f[R]
.SH AUTHORS
nick black <nickblack@linux.com>.