NAME

       libttyrec - a library for handling ttyrec files

SYNOPSIS

       #include <ttyrec.h>

       Link with -ltty.

DESCRIPTION

   Helper stream function:
       int     open_stream(int fd, const char* url, int mode, const char **error);
           This function opens a stream designated by the url.  If the given url ends in ".gz", ".xz", ".bz2" or
           ".zst"),  the  stream is assumed to be compressed and gets passed through the appropriate [un]packer.
           If the fd is not -1, it is the descriptor you already opened; if it is -1, the file is  opened.   The
           mode can be:

           SM_READ
           SM_WRITE
           SM_REPREAD
           SM_APPEND

           On  error, -1 is returned.  If you want the message, pass a non-null pointer error, it will be filled
           in.

   Format encoders:
       const char*   ttyrec_w_find_format(const char *format, const char *filename, const char *fallback);
           This function searches for a format that would fit the filename provided --  that  is,  abc.ttyrec.gz
           returns  "ttyrec".   If  no  known  extension  is  found,  the  function returns whatever you gave as
           fallback.  You can force a format yourself, in this case, it is only validated and if invalid,  0  is
           returned regardless of the other two arguments.

       recorder        ttyrec_w_open(int fd, const char *format, const char *filename, const struct timeval
       *ts);
           A  recorder  is  opened,  writing  to  the  file  fd;  if  it's  not  given (=-1), the function calls
           open_stream().  Recording is done in the given format, if not provided, the format is  guessed  based
           on the filename.  If you provide a timestamp ts, it becomes date of the recording.

       int     ttyrec_w_write(recorder r, const struct timeval *tm, const char *data, int len);
           A chunk of data of length len is written to recorder r, with timestamp tm.  Returns 1 if some sort of
           write error happened.

       int     ttyrec_w_close(recorder r);
           All pending data is flushed, recorder closed and its memory freed.  Returns 1 if there's some kind of
           failure.

       const char*   ttyrec_w_get_format_name(int i);
           You  can  use  this  function  to enumerate known write formats by calling it with i being subsequent
           numbers starting at 0.  An invalid i will return a null pointer.

       const char*   ttyrec_w_get_format_ext(const char *format);
           If the given write format is associated with a file extension, it is returned.

   Format decoders:
       const char*   ttyrec_r_find_format(const char *format, const char *filename, const char *fallback);
           See the _w_ function, except that read formats are searched instead.

       const char*   ttyrec_r_get_format_name(int i);
           ditto

       const char*   ttyrec_r_get_format_ext(const char *format);
           ditto

       int     ttyrec_r_play(int fd, const char *format, const char *filename,    void (*synch_init_wait)(const
       struct timeval *ts, void *arg),    void (*synch_wait)(const struct timeval *delay, void *arg),    void
       (*synch_print)(const char *data, int len, void *arg),    void *arg);
           This function decodes the file fd (opening filename if fd=-1).  If its contents contain the  date  of
           the  recording, you'll receive it through the callback synch_init_wait.  Between frames, the delay is
           passed through synch_wait.  The actual frame data  goes  through  synch_print.   Note  that  in  some
           formats,  two  or more consecutive delays or two consecutive frames can happen one after another.  If
           you provide an arbitrary arg, it will be passed to all callbacks.

           The function doesn't return until the end of input data.  Returns 1 on success, 0 on failure.

   The following functions deal with in-memory ttyrecs:
       ttyrec          ttyrec_init(tty vt);
           An empty one is allocated.  If a vt is provided, it becomes the screen that the ttyrec is  internally
           played on; otherwise, a blank 80x25 one is allocated.  The vt is consumed.

       ttyrec          ttyrec_load(int fd, const char *format, const char *filename, tty vt);
           This  function will load a ttyrec from the file designated with fd.  If it's not open yet (fd=-1), it
           will be opened with open_stream.  The ttyrec is played on the vt you provide -- or  on  a  new  80x25
           one.

       void            ttyrec_free(ttyrec tr);
           Destroys the in-memory ttyrec, freeing its memory.

       You  can  read  the  ttyrec's  data  while  it's being read; all functions are thread-safe with regard to
       reading.  The frames are stored in structures like this:

       typedef struct {
           struct timeval t;
           int len;
           char *data; } *ttyrec_frame;

       ttyrec_frame    ttyrec_seek(ttyrec tr, const struct timeval *t, tty *vt);
           Finds the frame that should be shown at time *t, or the first frame if t is null.  If vt is not-null,
           it will receive a terminal containing the screen at that frame.

       ttyrec_frame    ttyrec_next_frame(ttyrec tr, ttyrec_frame tfv);
           Returns the next frame after frame tfv, or null if tfv was the last.

       void            ttyrec_add_frame(ttyrec tr, const struct timeval *delay, const char *data, int len);
           Creates a new frame and appends it to ttyrec tr.

       int             ttyrec_save(ttyrec tr, int fd, const char *format, const char *filename, const struct
       timeval *selstart, const struct timeval *selend);
           Exports the ttyrec to a new file.  If selstart and/or selend are given, they designate the part  that
           should be exported -- if not, the whole is.

   struct timeval arithmetics:
       A handful of macros for operating on timeval values:

       tadd(t, d)
           t+=d;

       tsub(t, d)
           t-=d;

       tmul1000(t, m)
           t*=m/1000;

       tdiv1000(t, m)
           t/=m/1000;

       tcmp(t1, t2)
           If t1<t2, -1.  If t1>t2, +1.  0 otherwise.

SEE ALSO

       libtty(3)

0.19                                               2024-04-01                                       LIBTTYREC(3)