1notcurses_fds(3)                                              notcurses_fds(3)
2
3
4

NAME

6       notcurses_fds - dumping file descriptors and subprocesses to planes
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11              struct ncplane;
12              struct ncfdplane;
13              struct ncsubproc;
14
15              typedef struct ncfdplane_options {
16                void* curry; // parameter provided to callbacks
17                bool follow; // keep reading after hitting end?
18              } ncfdplane_options;
19
20              typedef struct ncsubproc_options {
21                void* curry; // parameter provided to callbacks
22                uint64_t restart_period;  // restart after exit
23              } ncsubproc_options;
24
25       typedef  int(ncfdplane_callback)(struct  ncfdplane  n, const void* buf,
26       size_t s, void* curry);
27
28       typedef int(ncfdplane_done_cb)(struct ncfdplane n, int  fderrno,  void*
29       curry);
30
31       struct  ncfdplane*  ncfdplane_create(struct  ncplane*  n,  const  ncfd‐
32       plane_options*  opts,   int   fd,   ncfdplane_callback   cbfxn,   ncfd‐
33       plane_done_cb donecbfxn);
34
35       struct ncplane* ncfdplane_plane(struct ncfdplane* n);
36
37       int ncfdplane_destroy(struct ncfdplane* n);
38
39       struct  ncsubproc*  ncsubproc_createv(struct  ncplane*  n, const ncsub‐
40       proc_options* opts, const char* bin, char* const arg[], ncfdplane_call‐
41       back cbfxn, ncfdplane_done_cb donecbfxn);
42
43       struct  ncsubproc*  ncsubproc_createvp(struct  ncplane* n, const ncsub‐
44       proc_options* opts, const char* bin, char* const arg[], ncfdplane_call‐
45       back cbfxn, ncfdplane_done_cb donecbfxn);
46
47       struct  ncsubproc*  ncsubproc_createvpe(struct ncplane* n, const ncsub‐
48       proc_options* opts, const char* bin, char*  const  arg[],  char*  const
49       env[], ncfdplane_callback cbfxn, ncfdplane_done_cb donecbfxn);
50
51       struct ncplane* ncsubproc_plane(struct ncsubproc* n);
52
53       int ncsubproc_destroy(struct ncsubproc* n);
54

DESCRIPTION

56       These widgets cause a file descriptor to be read until EOF, and written
57       to a scrolling ncplane.  The reading will take place  in  a  notcurses-
58       managed  context  (the particulars of this context are not defined, and
59       should not be depended upon), which will invoke the provided  callbacks
60       with  the  data read.  Essentially, they are simply portable interfaces
61       to asynchronous reading, with ncsubproc also providing subprocess  man‐
62       agement.
63
64       If  ncsubproc_destroy  is  called  before the subprocess has exited, it
65       will be sent a SIGKILL.  If ncsubproc_destroy or  ncfdplane_destroy  is
66       called  while  a  callback  is being invoked, the destroy function will
67       block until the callback is done being invoked.  If a user callback re‐
68       turns  non-0,  the calling object will destroy itself.  If a user call‐
69       back calls the relevant destroy function itself, the thread  will  exit
70       as  if  non-0  had been returned, and the ncsubproc's resources will at
71       that time be reclaimed.
72
73       It is essential that the destroy function be called once and only once,
74       whether  it  is  from  within the thread's context, or external to that
75       context.
76

NOTES

78       ncsubproc makes use of pidfds and pidfd_send_signal(2), and thus  makes
79       reliable  use of signals (it will never target a process other than the
80       true subprocess).
81

RETURN VALUES

SEE ALSO
84       pidfd_open(2), notcurses(3), notcurses_plane(3)
85

AUTHORS
87       nick black <nickblack@linux.com>.
88
89
90
91                                    v2.2.3                    notcurses_fds(3)



        

    


            
        

        

            Impressum