notcurses_error(3) man page #532

doc/man/index.html

@@ -28,6 +28,7 @@
   <a href="notcurses_cell.3.html">notcurses_cell</a>—operations on <tt>cell</tt> objects<br/>
   <a href="notcurses_channels.3.html">notcurses_channels</a>—operations on the <tt>channel</tt> type<br/>
   <a href="notcurses_directmode.3.html">notcurses_directmode</a>—minimal notcurses instances for styling text<br/>
+  <a href="notcurses_error.3.html">notcurses_error</a>—granular Notcurses error reporting<br/>
   <a href="notcurses_fade.3.html">notcurses_fade</a>—fading and pulsing for <tt>ncplane</tt>s<br/>
   <a href="notcurses_init.3.html">notcurses_init</a>—initialization<br/>
   <a href="notcurses_input.3.html">notcurses_input</a>—collecting input<br/>

doc/man/man3/notcurses.3.md

@@ -138,6 +138,7 @@ previous action.
 **notcurses_cell(3)**, **notcurses_channels(3)**,
 **notcurses_fade(3)**, **notcurses_init(3)**, **notcurses_input(3)**,
 **notcurses_directmode(3)**,
+**notcurses_error(3)**,
 **notcurses_lines(3)**,
 **notcurses_menu(3)**,
 **notcurses_multiselector(3)**,

doc/man/man3/notcurses_error.3.md

@@ -0,0 +1,36 @@
+% notcurses_error(3)
+% nick black <nickblack@linux.com>
+% v1.3.2
+
+# NAME
+
+notcurses_error - granular Notcurses error reporting
+
+# SYNOPSIS
+
+**#include <notcurses/ncerrs.h>**
+
+```c
+typedef enum {
+  NCERR_SUCCESS = 0,
+  NCERR_NOMEM = ENOMEM,
+  NCERR_EOF = 0x20464f45, // matches AVERROR_EOF
+} nc_err_e;
+
+# DESCRIPTION
+
+Various functions in Notcurses return granular information about the cause of
+an error. When done, this information is returned through an **nc_err_e**.
+
+# NOTES
+
+The goal is to abstract the union of errors returned by supported operating
+systems and the libraries on which Notcurses depends. Thus **nc_err_e** is
+a union of members of POSIX and FFmpeg.
+
+# RETURN VALUES
+
+# SEE ALSO
+
+**errno(3)**,
+**notcurses(3)**

doc/man/man3/notcurses_ncvisual.3.md

@@ -22,22 +22,22 @@ typedef int (*streamcb)(struct notcurses*, struct ncvisual*, void*);
 **bool notcurses_canopen(const struct notcurses* nc);**
 
 **struct ncvisual* ncplane_visual_open(struct ncplane* nc, const char* file,
-                                         int* averr);**
+                                         nc_err_e* err);**
 
 **struct ncvisual* ncvisual_open_plane(struct notcurses* nc, const char* file,
-                                         int* averr, int y, int x,
+                                         nc_err_e* err, int y, int x,
                                          ncscale_e style);**
 
 **void ncvisual_destroy(struct ncvisual* ncv);**
 
-**struct AVFrame* ncvisual_decode(struct ncvisual* nc, int* averr);**
+**struct AVFrame* ncvisual_decode(struct ncvisual* nc, nc_err_e* err);**
 
 **int ncvisual_render(const struct ncvisual* ncv, int begy, int begx,
                         int leny, int lenx);**
 
 **int ncvisual_simple_streamer(struct notcurses* nc, struct ncvisual* ncv, void* curry);**
 
-**int ncvisual_stream(struct notcurses* nc, struct ncvisual* ncv, int* averr,
+**int ncvisual_stream(struct notcurses* nc, struct ncvisual* ncv, nc_err_e* err,
                       float timescale, streamcb streamer, void* curry);**
 
 **struct ncplane* ncvisual_plane(struct ncvisual* ncv);**
@@ -61,9 +61,9 @@ if Notcurses was not built with FFmpeg support. **ncplane_visual_open** and
 **ncvisual_open_plane** return an **ncvisual** object on success, or **NULL**
 on failure. Success from these functions indicates that the specified **file**
 was opened, and enough data was read to make a firm codec identification. It
-does not mean that the entire file is properly-formed. On failure, **averr**
+does not mean that the entire file is properly-formed. On failure, **err**
 will be updated. **ncvisual_decode** returns a valid **AVFrame** on success, or
-**NULL** on error. It likewise updates **averr** in the event of an error.
+**NULL** on error. It likewise updates **err** in the event of an error.
 **ncvisual_render** returns the number of cells emitted, or -1 on error.
 
 # SEE ALSO