Console Pager

enum pager_state

Constants

PAGERST_OK: Normal output is happening
PAGERST_AT_LIMIT: No more output can be provided; the next call to pager_next() will return a user prompt
PAGERST_WAIT_USER: Waiting for the user to press a key
PAGERST_CLEAR_PROMPT: Clearing the prompt ready for more output
PAGERST_BYPASS: Pager is being bypassed
PAGERST_QUIT_SUPPRESS: Output is being suppressed after ‘q’ keypress

struct pager: pager state

Definition

struct pager {
  int line_count;
  int page_len;
  struct abuf buf;
  struct membuf mb;
  const char *overflow;
  char *nulch;
  int oldch;
  enum pager_state state;
  bool test_bypass;
};

Members

line_count: Number of lines output since last pause
page_len: Sets the height of the page in lines. The maximum lines to display before pausing is one less than this. Set from ‘pager’ env variable
buf: Buffer containing text to eventually be returned
mb: Circular buffer to manage buf
overflow: pointer to overflow text to send nexts
nulch: pointer to where a nul character was written, NULL if none
oldch: old character that was at nulch
state: current state of the pager state-machine
test_bypass: true if pager should behave as if in test mode (bypass all)

Description

The pager uses a buffer buf to hold text that it is in the process of sending out. This helps deal with the stdio puts() interface, which does not permit passing a string length, only a string, which means that strings must be nul-terminated. The termination is handled automatically by the pager.

If the text passed to pager_postn() is too large for buf then all the next will be written at once, without any paging, in the next call to pager_next().

The membuf mb is initialised one byte smaller than the abuf buf, so the last byte of buf is always available for writing a nul terminator. This means pager_next() can safely terminate the returned string without overflowing the underlying allocation.

The membuf mb is only used to feed out text in chunks, with a pager message (and a keypress wait) inserted between each chunk.

const char *pager_postn(struct pager *pag, bool use_pager, const char *s, int len): Add text to the input buffer for later handling

Parameters

struct pager *pag: Pager to use, may be NULL
bool use_pager: Whether or not to use the pager functionality
const char *s: Text to add
int len: Length of s in bytes

Description

If use_pager the text is added to the pager buffer and fed out a screenful at a time. This function calls pager_postn() after storing the text.

After calling pager_postn(), if it returns anything other than NULL, you must repeatedly call pager_next() until it returns NULL, otherwise text may be lost

If pag is NULL, this does nothing but return s

Return

text which should be sent to output, or NULL if there is no more. If !use_pager this just returns s and does not affect the pager state

const char *pager_post(struct pager *pag, bool use_pager, const char *s): Add a nul-terminated string to the pager input buffer

Parameters

struct pager *pag: Pager to use, may be NULL
bool use_pager: Whether or not to use the pager functionality
const char *s: Nul-terminated text to add

Description

Convenience wrapper around pager_postn() for nul-terminated strings.

Return

text which should be sent to output, or NULL if there is no more

const char *pager_next(struct pager *pag, bool use_pager, int ch): Returns the next screenful of text to show

Parameters

struct pager *pag: Pager to use
bool use_pager: Whether or not to use the pager functionality
int ch: Key that the user has pressed, or 0 if none

Description

If this function returns PAGER_WAITING then the caller must check for user input and pass in the keypress in the next call to pager_next(). It can busy-wait for a keypress, if desired, since pager_next() will only ever return PAGER_WAITING until ch is non-zero.

When the pager prompts for user input, pressing SPACE continues to the next page, while pressing capital ‘Q’ puts the pager into bypass mode and disables further paging. Pressing ‘q’ quits and suppresses all output until the next command prompt.

Return

text which should be sent to output, or PAGER_WAITING if waiting for the user to press a key, or NULL if there is no more text. If !use_pager this just returns NULL and does not affect the pager state

bool pager_active(struct pager *pag): check if pager needs to process output

Parameters

struct pager *pag: Pager to check, may be NULL

Description

Returns true only when the pager is genuinely active and needs to process output (not bypassed or in test bypass mode).

Return

true if the pager is active

bool pager_set_bypass(struct pager *pag, bool bypass): put the pager into bypass mode

Parameters

struct pager *pag: Pager to use, may be NULL in which case this function does nothing
bool bypass: true to put the pager in bypass mode, false for normal mode

Description

This is used when output is not connected to a terminal. Bypass mode stops the pager from doing anything to interrupt output.

Return

old value of the bypass flag

bool pager_set_test_bypass(struct pager *pag, bool bypass): put the pager into test bypass mode

Parameters

struct pager *pag: Pager to use, may be NULL in which case this function does nothing
bool bypass: true to put the pager in test bypass mode, false for normal

Description

This is used for tests. Test bypass mode stops the pager from doing anything to interrupt output, regardless of the current pager state.

Return

old value of the test bypass flag

void pager_reset(struct pager *pag): reset the line count in the pager

Parameters

struct pager *pag: Pager to update

Description

Sets line_count to zero so that the pager starts afresh with its counting.

void pager_clear_quit(struct pager *pag): Clear quit suppression mode

Parameters

struct pager *pag: Pager to update, may be NULL in which case this function does nothing

Description

If the pager is in PAGERST_QUIT_SUPPRESS state, this resets it to normal operation (PAGERST_OK). This is typically called at the start of cli_readline_into_buffer() to allow new commands to display output normally.

void pager_uninit(struct pager *pag): Uninit the pager

Parameters

struct pager *pag: Pager to uninit

Description

Frees all memory and also pag

void pager_set_page_len(struct pager *pag, int page_len): Set the page length of a pager

Parameters

struct pager *pag: Pager to use
int page_len: Page length to set

int pager_init(struct pager **pagp, int page_len, int buf_size): Set up a new pager

Parameters

struct pager **pagp: Returns allocaed pager, on success
int page_len: Number of lines per page
int buf_size: Buffer size to use in bytes, this is the maximum amount of output that can be paged

Return

0 if OK, -ENOMEM if out of memory