TSDuck Version 3.32-2769 (TSDuck - The MPEG Transport Stream Toolkit)
ts::OutputPager Class Reference

Send application output to a "pager" application such as "more" or "less". More...

Inheritance diagram for ts::OutputPager:
Collaboration diagram for ts::OutputPager:

Public Types

enum  InputMode {
  STDIN_PARENT,
  STDIN_PIPE,
  STDIN_NONE
}
 How to standard input in the created process. More...
 
enum  OutputMode {
  KEEP_BOTH,
  STDOUT_ONLY,
  STDERR_ONLY,
  STDOUT_PIPE,
  STDOUTERR_PIPE
}
 How to merge standard output and standard error in the created process. More...
 
typedef std::basic_ostream< char > SuperClass
 Explicit reference to the public superclass.
 
enum  WaitMode {
  ASYNCHRONOUS,
  SYNCHRONOUS,
  EXIT_PROCESS
}
 How to wait for the created process when close() is invoked. More...
 

Public Member Functions

 OutputPager (const UString &envName=DEFAULT_PAGER, bool stdoutOnly=false)
 Default constructor. More...
 
virtual ~OutputPager () override
 Destructor.
 
void abortPipeReadWrite ()
 Abort any currenly input/output operation in the pipe. More...
 
bool canPage () const
 Check if we can run a pager. More...
 
bool close (Report &report)
 Close the pipe. More...
 
virtual bool endOfStream () override
 Check if the end of stream was reached. More...
 
bool getIgnoreAbort () const
 Get "ignore abort". More...
 
bool isBroken () const
 Check if the pipe was broken. More...
 
bool isOpen () const
 Check if the process is running and the pipe is open (when used). More...
 
bool isSynchronous () const
 Check if synchronous mode is active (ie. More...
 
bool open (bool synchronous, size_t buffer_size, Report &report)
 Create the process, open the pipe. More...
 
bool open (const UString &command, WaitMode wait_mode, size_t buffer_size, Report &report, OutputMode out_mode, InputMode in_mode)
 Create the process, open the optional pipe. More...
 
UString pagerCommand () const
 Get the pager command which is used. More...
 
virtual bool readStreamChunks (void *addr, size_t max_size, size_t chunk_size, size_t &ret_size, Report &report)
 Read chunks of data from the stream. More...
 
virtual bool readStreamComplete (void *addr, size_t max_size, size_t &ret_size, Report &report)
 Read complete data from the stream. More...
 
virtual bool readStreamPartial (void *addr, size_t max_size, size_t &ret_size, Report &report) override
 Read partial data from the stream. More...
 
void setIgnoreAbort (bool on)
 Set "ignore abort". More...
 
bool write (const UString &text, Report &report)
 Write data to the pipe (received at process' standard input). More...
 
virtual bool writeStream (const void *addr, size_t size, size_t &written_size, Report &report) override
 Write data to the stream. More...
 

Static Public Member Functions

static bool Launch (const UString &command, Report &report, OutputMode out_mode=KEEP_BOTH, InputMode in_mode=STDIN_PARENT)
 This static method asynchronously launches a command, without pipe, without waiting for the completion of the command process. More...
 

Static Public Attributes

static const UChar *const DEFAULT_PAGER
 Default name of the environment variable containing the pager command. More...
 
static constexpr size_t DEFAULT_STREAM_BUFFER_SIZE = 1024
 Default stream buffer size in bytes.
 

Protected Member Functions

virtual bool writeStreamBuffer (const void *addr, size_t size) override
 Write buffered data to underlying output devicen whatever it is. More...
 

Detailed Description

Send application output to a "pager" application such as "more" or "less".

Paging is done on stdout or stderr or both, depending on which is a terminal. If neither stdout nor stderr are terminals, paging is not allowed.

Member Enumeration Documentation

◆ WaitMode

enum ts::ForkPipe::WaitMode
inherited

How to wait for the created process when close() is invoked.

No pipe can be used with EXIT_PROCESS because there would be nobody on the other end of the pipe.

Enumerator
ASYNCHRONOUS 

Don't wait, close() will return immediately.

SYNCHRONOUS 

Wait for process completion during close().

EXIT_PROCESS 

Exit parent process during open(). UNIX: call exec(), Windows: call exit() after process creation.

◆ InputMode

enum ts::ForkPipe::InputMode
inherited

How to standard input in the created process.

The pipe can be used either on input or output, but not both. So, STDIN_PIPE is also forbidden with output mode is either STDOUT_PIPE or STDOUTERR_PIPE.

Enumerator
STDIN_PARENT 

Keep same stdin as current (parent) process.

STDIN_PIPE 

Use the pipe as stdin.

STDIN_NONE 

No standard input (the null device in fact).

◆ OutputMode

enum ts::ForkPipe::OutputMode
inherited

How to merge standard output and standard error in the created process.

Enumerator
KEEP_BOTH 

Keep same stdout and stderr as current (parent) process.

STDOUT_ONLY 

Merge stderr into current stdout.

STDERR_ONLY 

Merge stdout into current stderr.

STDOUT_PIPE 

Use the pipe to receive stdout, keep same stderr as current (parent) process.

STDOUTERR_PIPE 

Use the pipe to receive a merge of stdout and stderr.

Constructor & Destructor Documentation

◆ OutputPager()

ts::OutputPager::OutputPager ( const UString envName = DEFAULT_PAGER,
bool  stdoutOnly = false 
)
explicit

Default constructor.

Parameters
[in]envNameName of the optional environment variable containing the pager command name.
[in]stdoutOnlyIf true, use only stdout. If false, if stdout is not a terminal but stderr is one, then use stderr for paging.

Member Function Documentation

◆ canPage()

bool ts::OutputPager::canPage ( ) const
inline

Check if we can run a pager.

To run a pager, we must have found a valid pager command and either stdout or stderr must be a terminal.

Returns
True if we can page.

◆ pagerCommand()

UString ts::OutputPager::pagerCommand ( ) const
inline

Get the pager command which is used.

Returns
The pager command which is used.

◆ open() [1/2]

bool ts::OutputPager::open ( bool  synchronous,
size_t  buffer_size,
Report report 
)

Create the process, open the pipe.

Parameters
[in]synchronousIf true, wait for process termination in close().
[in]buffer_sizeThe pipe buffer size in bytes. Used on Windows only. Zero means default.
[in,out]reportWhere to report errors.
Returns
True on success, false on error.

◆ write()

bool ts::OutputPager::write ( const UString text,
Report report 
)

Write data to the pipe (received at process' standard input).

Parameters
[in]textText to write.
[in,out]reportWhere to report errors.
Returns
True on success, false on error.

◆ open() [2/2]

bool ts::ForkPipe::open ( const UString command,
WaitMode  wait_mode,
size_t  buffer_size,
Report report,
OutputMode  out_mode,
InputMode  in_mode 
)
inherited

Create the process, open the optional pipe.

Parameters
[in]commandThe command to execute.
[in]wait_modeHow to wait for process termination in close().
[in]buffer_sizeThe pipe buffer size in bytes. Used on Windows only. Zero means default.
[in,out]reportWhere to report errors.
[in]out_modeHow to handle stdout and stderr.
[in]in_modeHow to handle stdin. Use the pipe by default. When set to KEEP_STDIN, no pipe is created.
Returns
True on success, false on error. Do not return on success when wait_mode is EXIT_PROCESS.

◆ close()

bool ts::ForkPipe::close ( Report report)
inherited

Close the pipe.

Optionally wait for process termination if wait_mode was SYNCHRONOUS on open().

Parameters
[in,out]reportWhere to report errors.
Returns
True on success, false on error.

◆ isOpen()

bool ts::ForkPipe::isOpen ( ) const
inlineinherited

Check if the process is running and the pipe is open (when used).

Returns
True if the process is running and the pipe is open.

◆ isBroken()

bool ts::ForkPipe::isBroken ( ) const
inlineinherited

Check if the pipe was broken.

Returns
True if was broken (unexpected process termination for instance).

◆ isSynchronous()

bool ts::ForkPipe::isSynchronous ( ) const
inlineinherited

Check if synchronous mode is active (ie.

will wait for process termination).

Returns
True if synchronous mode is active.

◆ setIgnoreAbort()

void ts::ForkPipe::setIgnoreAbort ( bool  on)
inlineinherited

Set "ignore abort".

Parameters
[in]onIf true and the process aborts, do not report error when writing data. when writing data.

◆ getIgnoreAbort()

bool ts::ForkPipe::getIgnoreAbort ( ) const
inlineinherited

Get "ignore abort".

Returns
True if, when the process aborts, do not report error when writing data.

◆ abortPipeReadWrite()

void ts::ForkPipe::abortPipeReadWrite ( )
inherited

Abort any currenly input/output operation in the pipe.

The pipe is left in a broken state and can be only closed.

◆ Launch()

static bool ts::ForkPipe::Launch ( const UString command,
Report report,
OutputMode  out_mode = KEEP_BOTH,
InputMode  in_mode = STDIN_PARENT 
)
staticinherited

This static method asynchronously launches a command, without pipe, without waiting for the completion of the command process.

Parameters
[in]commandThe command to execute.
[in,out]reportWhere to report errors.
[in]out_modeHow to handle stdout and stderr. Keep both by default. Output modes using pipes are forbidden.
[in]in_modeHow to handle stdin. Keep the parent input by default. Input modes using pipes are forbidden.
Returns
True on success, false on error.

◆ endOfStream()

virtual bool ts::ForkPipe::endOfStream ( )
overridevirtualinherited

Check if the end of stream was reached.

Returns
True on end of stream, false otherwise.

Implements ts::AbstractReadStreamInterface.

◆ readStreamPartial()

virtual bool ts::ForkPipe::readStreamPartial ( void *  addr,
size_t  max_size,
size_t &  ret_size,
Report report 
)
overridevirtualinherited

Read partial data from the stream.

Wait and read at least one byte. Don't try to read exactly max_size bytes. If ret_size is less than max_bytes, it is possible to read more.

Parameters
[out]addrAddress of the buffer for the incoming data.
[in]max_sizeMaximum size in bytes of the buffer.
[out]ret_sizeReturned input size in bytes. If zero, end of file has been reached or an error occurred.
[in,out]reportWhere to report errors.
Returns
True on success, false on error.

Implements ts::AbstractReadStreamInterface.

◆ writeStream()

virtual bool ts::ForkPipe::writeStream ( const void *  addr,
size_t  size,
size_t &  written_size,
Report report 
)
overridevirtualinherited

Write data to the stream.

All bytes are written to the stream, blocking or retrying when necessary.

Parameters
[in]addrAddress of the data to write.
[in]sizeSize in bytes of the data to write.
[out]written_sizeActually written size in bytes. Can be less than size in case of error in the middle of the write.
[in,out]reportWhere to report errors.
Returns
True on success, false on error.

Implements ts::AbstractWriteStreamInterface.

◆ writeStreamBuffer()

virtual bool ts::ForkPipe::writeStreamBuffer ( const void *  addr,
size_t  size 
)
overrideprotectedvirtualinherited

Write buffered data to underlying output devicen whatever it is.

Must be implemented by subclasses.

Parameters
[in]addrBuffered data address.
[in]sizeBuffered data size in bytes.
Returns
True on success, false on error.

Implements ts::AbstractOutputStream.

◆ readStreamComplete()

virtual bool ts::AbstractReadStreamInterface::readStreamComplete ( void *  addr,
size_t  max_size,
size_t &  ret_size,
Report report 
)
virtualinherited

Read complete data from the stream.

Wait and read exactly max_size bytes. If ret_size is less than max_bytes, it is not possible to read more. End of file has probably been reached.

Parameters
[out]addrAddress of the buffer for the incoming data.
[in]max_sizeMaximum size in bytes of the buffer.
[out]ret_sizeReturned input size in bytes.
[in,out]reportWhere to report errors.
Returns
True on success, false on error.

◆ readStreamChunks()

virtual bool ts::AbstractReadStreamInterface::readStreamChunks ( void *  addr,
size_t  max_size,
size_t  chunk_size,
size_t &  ret_size,
Report report 
)
virtualinherited

Read chunks of data from the stream.

Parameters
[out]addrAddress of the buffer for the incoming data.
[in]max_sizeMaximum size in bytes of the buffer.
[in]chunk_sizeIf not zero, make sure that the input size is always a multiple of chunk_size. If the initial read ends in the middle of a chunk, read again and again, up to the end of the current chunk or end of file.
[out]ret_sizeReturned input size in bytes.
[in,out]reportWhere to report errors.
Returns
True on success, false on error.

Member Data Documentation

◆ DEFAULT_PAGER

const UChar* const ts::OutputPager::DEFAULT_PAGER
static

Default name of the environment variable containing the pager command.

The default environment variable is PAGER.


The documentation for this class was generated from the following file: