REDI_BASIC_PSTREAMBUF(3)

📦
version 1.0.4 · 2 versions
, in ubuntu resolute, ubuntu stonking

💖 redi::basic_pstreambuf — Library Functions Manual, section 3 💖

okay bestie, welcome to the Library Functions Manual page for redi::basic_pstreambuf, section 3. this is the template class that's literally the engine room of PStreams, and yeah it's a long one, so we're doing this in two parts. strap in, hydrate, let's go 🫶

✨ NAME ✨

redi::basic_pstreambuf — Class template for stream buffer. that's the whole vibe. it's a streambuf, it's a template, it slays 💅

✨ SYNOPSIS ✨

#include <pstream.h>

Inherits std::basic_streambuf< CharT, std::char_traits< CharT > >, and redi::pstreams. it's giving "rich family tree" 🌳✨

🎀 Public Types 🎀

  • typedef CharT char_type
  • typedef Traits traits_type
  • typedef traits_type::int_type int_type
  • typedef traits_type::off_type off_type
  • typedef traits_type::pos_type pos_type
  • typedef fd_type fd_t
  • typedef std::ios_base::openmode pmode — Type used to specify how to connect to the process. lowkey the mode selector of it all.
  • typedef std::vector< std::string > argv_type — Type used to hold the arguments for a command. it's the lil list of args, iconic.
  • typedef int fd_type — Type used for file descriptors. just an int bestie, no cap.

🌸 Public Member Functions 🌸

  • basic_pstreambuf () — Default constructor.
  • basic_pstreambuf (const std::string &cmd, pmode mode) — Constructor that initialises the buffer with cmd.
  • basic_pstreambuf (const std::string &file, const argv_type &argv, pmode mode) — Constructor that initialises the buffer with file and argv.
  • ~basic_pstreambuf () — Destructor.
  • basic_pstreambuf * open (const std::string &cmd, pmode mode) — Initialise the stream buffer with cmd.
  • basic_pstreambuf * open (const std::string &file, const argv_type &argv, pmode mode) — Initialise the stream buffer with file and argv.
  • basic_pstreambuf * close () — Close the stream buffer and wait for the process to exit.
  • basic_pstreambuf * kill (int signal=SIGTERM) — Send a signal to the process.
  • basic_pstreambuf * killpg (int signal=SIGTERM) — Send a signal to the process' process group.
  • void peof () — Close the pipe connected to the process' stdin.
  • bool read_err (bool readerr=true) — Change active input source.
  • bool is_open () const — Report whether the stream buffer has been initialised.
  • bool exited () — Report whether the process has exited.
  • int status () const — Return the exit status of the process.
  • int error () const — Return the error number (errno) for the most recent failed operation.

💜 Static Public Attributes 💜

  • static const pmode pstdin = std::ios_base::out — Write to stdin. 👈 we're the ones writing, they're listening.
  • static const pmode pstdout = std::ios_base::in — Read from stdout.
  • static const pmode pstderr = std::ios_base::app — Read from stderr.
  • static const pmode newpg = std::ios_base::trunc — Create a new process group for the child process. main character needs her own group fr.

🦋 Protected Types 🦋

  • enum buf_read_src { rsrc_out = 0, rsrc_err = 1 } — Enumerated type to indicate whether stdout or stderr is to be read. pick your source, bestie.
  • enum { bufsz = 32, pbsz = 2 }

🌈 Protected Member Functions 🌈

  • int_type overflow (int_type c) — Transfer characters to the pipe when character buffer overflows.
  • int_type underflow () — Transfer characters from the pipe when the character buffer is empty.
  • int_type pbackfail (int_type c=traits_type::eof()) — Make a character available to be returned by the next extraction.
  • int sync () — Write any buffered characters to the stream.
  • std::streamsize xsputn (const char_type *s, std::streamsize n) — Insert multiple characters into the pipe.
  • std::streamsize write (const char_type *s, std::streamsize n) — Insert a sequence of characters into the pipe.
  • std::streamsize read (char_type *s, std::streamsize n) — Extract a sequence of characters from the pipe.
  • std::streamsize showmanyc () — Report how many characters can be read from active input without blocking.
  • pid_t fork (pmode mode) — Initialise pipes and fork process.
  • int wait (bool nohang=false) — Wait for the child process to exit.
  • fd_type & wpipe () — Return the file descriptor for the output pipe.
  • fd_type & rpipe () — Return the file descriptor for the active input pipe.
  • fd_type & rpipe (buf_read_src which) — Return the file descriptor for the specified input pipe.
  • void create_buffers (pmode mode)
  • void destroy_buffers (pmode mode)
  • bool empty_buffer () — Writes buffered characters to the process' stdin pipe.
  • bool fill_buffer (bool non_blocking=false)
  • char_type * rbuffer () — Return the active input buffer.
  • buf_read_src switch_read_buffer (buf_read_src)

(Note that these are not member symbols. so like, cousins, not siblings 💫)

  • void close_fd (pstreams::fd_type &fd) — Helper function to close a file descriptor.
  • template<int N> void close_fd_array (pstreams::fd_type(&fds)[N]) — Helper function to close an array of file descriptors.

✨ Detailed Description ✨

template<typename CharT, typename Traits = std::char_traits<CharT>>
class redi::basic_pstreambuf< CharT, Traits >

"Class template for stream buffer.

Provides underlying streambuf functionality for the PStreams classes."

that's it, that's the whole résumé. it's the streambuf underneath all the pretty PStreams classes — the scaffolding behind the fit 🏗️💅

🎀 Member Typedef Documentation 🎀

fd_t

template<typename CharT, typename Traits = std::char_traits<CharT>> typedef
    fd_type redi::basic_pstreambuf< CharT, Traits >::fd_t
Deprecated — use pstreams::fd_type instead. okay so this one is giving "vintage, but the vibe has moved on" 🕰️ still valid, just not the moment anymore.

🌸 Member Enumeration Documentation 🌸

anonymous enum [protected], [inherited]

Enumerators:

  • bufsz — Size of pstreambuf buffers. it's 32. no notes.
  • pbsz — Number of putback characters kept. it's 2. tiny but mighty.

💖 Constructor & Destructor Documentation 💖

basic_pstreambuf ()

template<typename C, typename T> redi::basic_pstreambuf< C, T
    >::basic_pstreambuf () [inline]

Default constructor. Creates an uninitialised stream buffer. yes bestie, she exists, she's just not doing anything yet — potential is a vibe ✨

Referenced by kill(), killpg(), open(), and open().

basic_pstreambuf (const std::string & cmd, pmode mode)

template<typename C, typename T> redi::basic_pstreambuf< C, T
    >::basic_pstreambuf (const std::string & cmd, pmode mode) [inline]

Constructor that initialises the buffer with cmd. Initialises the stream buffer by calling open() with the supplied arguments. so it's the constructor that hands off to open(), classic delegation moment 🫶

Parameters

  • cmd — a string containing a shell command.
  • mode — the I/O mode to use when opening the pipe.

See also — open()

References open().

basic_pstreambuf (const std::string & file, const argv_type & argv, pmode mode)

template<typename C, typename T> redi::basic_pstreambuf< C, T
    >::basic_pstreambuf (const std::string & file, const argv_type & argv,
    pmode mode) [inline]

Constructor that initialises the buffer with file and argv. Initialises the stream buffer by calling open() with the supplied arguments. same energy, no shell involved this time 🌟

Parameters

  • file — a string containing the name of a program to execute.
  • argv — a vector of argument strings passsed to the new program. (yes, "passsed" — we keep the typo, we respect the lore 🙈)
  • mode — the I/O mode to use when opening the pipe.

See also — open()

References open().

~basic_pstreambuf ()

template<typename C, typename T> redi::basic_pstreambuf< C, T
    >::~basic_pstreambuf () [inline]

Destructor. Closes the stream by calling close(). she knows how to make an exit, periodt 💅

See also — close()

References close().

🌈 Member Function Documentation 🌈

close ()

template<typename C, typename T> basic_pstreambuf< C, T > *
    redi::basic_pstreambuf< C, T >::close ()

Close the stream buffer and wait for the process to exit. Closes all pipes and calls wait() to wait for the process to finish. If an error occurs the error code will be set to one of the possible errors for waitpid(). See your system's documentation for these errors. so like, it's not just closing the door, it's waiting for your friend to actually leave the party 🚪👋

Returns — this on successful close or NULL if there is no process to close or if an error occurs.

References error(), is_open(), redi::pstreams::pstderr, redi::pstreams::pstdin, redi::pstreams::pstdout, sync(), and wait().

Referenced by fork(), open(), and ~basic_pstreambuf().

empty_buffer () [protected]

template<typename C, typename T> bool redi::basic_pstreambuf< C, T
    >::empty_buffer () [protected]

Writes buffered characters to the process' stdin pipe. dumping the stash into the pipe, very "clearing my camera roll" energy 📤

Returns — true if the buffer was emptied, false otherwise.

References write().

Referenced by overflow(), sync(), and xsputn().

error () const

template<typename C, typename T> int redi::basic_pstreambuf< C, T >::error
    () const [inline]

Return the error number (errno) for the most recent failed operation. it's the receipts of what went wrong most recently 🧾

Returns — The error code of the most recently failed operation, or zero.

Referenced by close().

exited ()

template<typename C, typename T> bool redi::basic_pstreambuf< C, T >::exited
    () [inline]

Report whether the process has exited. This function can call pstreambuf::wait() and so may change the object's state if the child process has already exited. ⚠️ so heads up: asking the question can change the answer's context — side effects, bestie, watch out.

Returns — True if the associated process has exited, false otherwise.

See also — basic_pstreambuf<C,T>::wait()

References wait().

Referenced by kill(), and sync().

fill_buffer (bool non_blocking = false) [protected]

template<typename C, typename T> bool redi::basic_pstreambuf< C, T
    >::fill_buffer (bool non_blocking = false) [protected]

Returns — true if the buffer was filled, false otherwise.

References redi::pstreams::bufsz, redi::pstreams::pbsz, rbuffer(), read(), and rpipe().

Referenced by showmanyc(), and underflow().

fork (pmode mode) [protected]

template<typename C, typename T> pid_t redi::basic_pstreambuf< C, T >::fork
    (pmode mode) [protected]

Initialise pipes and fork process. Creates pipes as specified by mode and calls fork() to create a new process. If the fork is successful the parent process stores the child's PID and the opened pipes and the child process replaces its standard streams with the opened pipes. literally the moment of creation, the origin story 🌱✨

If an error occurs the error code will be set to one of the possible errors for pipe() or fork(). See your system's documentation for these error codes.

Parameters

  • mode — an OR of pmodes specifying which of the child's standard streams to connect to.

Returns — On success the PID of the child is returned in the parent's context and zero is returned in the child's context. On error -1 is returned and the error code is set appropriately.

References close(), fork(), redi::pstreams::newpg, redi::pstreams::pstderr, redi::pstreams::pstdin, and redi::pstreams::pstdout.

Referenced by fork(), open(), and open().

is_open () const

template<typename C, typename T> bool redi::basic_pstreambuf< C, T
    >::is_open () const [inline]

Report whether the stream buffer has been initialised. Unlike pstreambuf::exited(), this function will not call wait() and so will not change the object's state. This means that once a child process is executed successfully this function will continue to return true even after the process exits (until wait() is called.) 👀 so it's the chill one — it does NOT go poking the process, it just tells you what it remembers.

Returns — true if a previous call to open() succeeded and wait() has not been called and determined that the process has exited, false otherwise.

Referenced by close(), kill(), killpg(), open(), open(), and wait().

kill (int signal = SIGTERM)

template<typename C, typename T> basic_pstreambuf< C, T > *
    redi::basic_pstreambuf< C, T >::kill (int signal = SIGTERM) [inline]

Send a signal to the process. Sends the specified signal to the process. A signal can be used to terminate a child process that would not exit otherwise. sometimes you gotta send the message, not ask nicely 💀

If an error occurs the error code will be set to one of the possible errors for kill(). See your system's documentation for these errors.

Parameters

  • signal — A signal to send to the child process.

kill(), the encore 💅

  • Returns — this or NULL if kill() fails.
References: basic_pstreambuf(), exited(), is_open(), and kill(). Referenced by kill().

killpg 🌸

template<typename C, typename T> basic_pstreambuf< C, T > *
redi::basic_pstreambuf< C, T >::killpg (int signal = SIGTERM) [inline]

okay so bestie, this one sends a signal to the process' process group. Not just the child — the whole group. You send the signal you picked to the process group of the child process. A signal can be used to terminate a child process that would not exit otherwise, or to kill the process and its own children. it's giving "clean up your whole little family tree" energy 🔥

If an error occurs, the error code will be set to one of the possible errors for getpgid() or kill(). See your system's documentation for these errors, fr fr, go read it. And here's the spicy bit: if the child is in the current process group then NULL will be returned and the error code set to EPERM. 😭

Parameters

  • signal — a signal to send to the child process.

Returns

  • this on success or NULL on failure.
References: basic_pstreambuf(), is_open(), and killpg(). Referenced by killpg().

open() — the string-and-shell one 🐚

template<typename C, typename T> basic_pstreambuf< C, T > *
redi::basic_pstreambuf< C, T >::open (const std::string & command, pmode mode)

Initialise the stream buffer with cmd. Starts a new process by passing command to the shell (/bin/sh) and opens pipes to the process with the specified mode. classic "let the shell handle it" behaviour, and honestly? iconic ✨

If mode contains pstdout the initial read source will be the child process' stdout, otherwise if mode contains pstderr the initial read source will be the child's stderr.

Will duplicate the actions of the shell in searching for an executable file if the specified file name does not contain a slash (/) character.

Warning ⚠️ There is no way to tell whether the shell command succeeded. This function will always succeed unless resource limits (such as memory usage, or number of processes or open files) are exceeded. This means is_open() will return true even if command cannot be executed. Use pstreambuf::open(const std::string&, const argv_type&, pmode) if you need to know whether the command failed to execute. bestie this is the trap, don't fall in it 💀

Parameters

  • command — a string containing a shell command.
  • mode — a bitwise OR of one or more of out, in, err.

Returns

  • NULL if the shell could not be started or the pipes could not be opened, this otherwise.

See also

References: basic_pstreambuf(), fork(), is_open(), and open(). Referenced by basic_pstreambuf(), basic_pstreambuf(), and open().

open() — the file-and-argv one 🎀

template<typename C, typename T> basic_pstreambuf< C, T > *
redi::basic_pstreambuf< C, T >::open (const std::string & file, const argv_type & argv, pmode mode)

Initialise the stream buffer with file and argv. Starts a new process by executing file with the arguments in argv and opens pipes to the process with the specified mode. no shell middleman, just straight to business, we love a direct communicator 💅

By convention argv[0] should be the file name of the file being executed.

If mode contains pstdout the initial read source will be the child process' stdout, otherwise if mode contains pstderr the initial read source will be the child's stderr.

Will duplicate the actions of the shell in searching for an executable file if the specified file name does not contain a slash (/) character.

Iff file is successfully executed then is_open() will return true. Otherwise, pstreambuf::error() can be used to obtain the value of errno that was set by execvp(3) in the child process. (yes it really says "Iff", that's not a typo, that's a flex 😌)

The exit status of the new process will be returned by pstreambuf::status() after pstreambuf::exited() returns true.

Parameters

  • file — a string containing the pathname of a program to execute.
  • argv — a vector of argument strings passed to the new program.
  • mode — a bitwise OR of one or more of out, in and err.

Returns

  • NULL if a pipe could not be opened or if the program could not be executed, this otherwise.

See also

References: basic_pstreambuf(), close(), fork(), is_open(), read(), wait(), and write().

overflow() 🫗

template<typename C, typename T> basic_pstreambuf< C, T >::int_type
redi::basic_pstreambuf< C, T >::overflow (int_type c) [protected]

Transfer characters to the pipe when character buffer overflows. Called when the internal character buffer is not present or is full, to transfer the buffer contents to the pipe. it's the "my cup runneth over" moment 🥤

Parameters

  • c — a character to be written to the pipe.

Returns

  • traits_type::eof() if an error occurs, otherwise if c is not equal to traits_type::eof() it will be buffered and a value other than traits_type::eof() returned to indicate success.
References: empty_buffer().

pbackfail() 💫

template<typename C, typename T> basic_pstreambuf< C, T >::int_type
redi::basic_pstreambuf< C, T >::pbackfail (int_type c = traits_type::eof()) [protected]

Make a character available to be returned by the next extraction. Attempts to make c available as the next character to be read by sgetc(). it's literally putting a character back where you found it, main character un-reads their own message energy 🙈

Parameters

  • c — a character to make available for extraction.

Returns

  • c if the character can be made available, traits_type::eof() otherwise.

peof() 🚪

template<typename C, typename T> void redi::basic_pstreambuf< C, T >::peof () [inline]

Close the pipe connected to the process' stdin. Closes the output pipe, causing the child process to receive the end-of-file indicator on subsequent reads from its stdin stream. basically telling the child "that's all bestie, no more for you" 💖

References: redi::pstreams::pstdin, and sync(). Referenced by redi::basic_opstream< char >::peof().

rbuffer() 📥

template<typename C, typename T> basic_pstreambuf< C, T >::char_type *
redi::basic_pstreambuf< C, T >::rbuffer () [inline],  [protected]

Return the active input buffer.

Returns

  • a pointer to the start of the active input buffer area.
Referenced by fill_buffer().

read() 📖

template<typename C, typename T> std::streamsize redi::basic_pstreambuf< C, T >::read (char_type * s, std::streamsize n) [inline],  [protected]

Extract a sequence of characters from the pipe. Reads up to n characters from the pipe to the buffer s.

Parameters

  • s — character buffer.
  • n — buffer length.

Returns

  • the number of characters read.
References: read(), and rpipe(). Referenced by fill_buffer(), open(), and read().

read_err() 🔀

template<typename C, typename T> bool redi::basic_pstreambuf< C, T >::read_err (bool readerr = true) [inline]

Change active input source. Toggle the stream used for reading. If readerr is true then the process' stderr output will be used for subsequent extractions, if readerr is false the the process' stdout will be used. (the double "the the" is in the source, we keep the source, we respect the source ✨)

Parameters

  • readerr — true to read stderr, false to read stdout.

Returns

  • true if the requested stream is open and will be used for subsequent extractions, false otherwise.

rpipe() — no args edition 🚰

template<typename C, typename T> pstreams::fd_type & redi::basic_pstreambuf< C, T >::rpipe () [inline],  [protected]

Return the file descriptor for the active input pipe.

Returns

  • a reference to the active input file descriptor
Referenced by fill_buffer(), read(), and showmanyc().

rpipe() — which edition 🚰

template<typename C, typename T> pstreams::fd_type & redi::basic_pstreambuf< C, T >::rpipe (buf_read_src which) [inline],  [protected]

Return the file descriptor for the specified input pipe.

Returns

  • a reference to the specified input file descriptor

status() 📊

template<typename C, typename T> int redi::basic_pstreambuf< C, T >::status () const [inline]

Return the exit status of the process.

Returns

  • The exit status of the child process, or -1 if wait() has not yet been called to wait for the child to exit.

See also

  • basic_pstreambuf<C,T>::wait()

underflow() 🫙

template<typename C, typename T> basic_pstreambuf< C, T >::int_type
redi::basic_pstreambuf< C, T >::underflow () [protected]

Transfer characters from the pipe when the character buffer is empty. Called when the internal character buffer is is empty, to re-fill it from the pipe. (again, "is is", that's the source talking, not me 😭)

Returns

  • The first available character in the buffer, or traits_type::eof() in case of failure.
References: fill_buffer().

wait() ⏳

template<typename C, typename T> int redi::basic_pstreambuf< C, T >::wait (bool nohang = false) [protected]

Wait for the child process to exit. Suspends execution and waits for the associated process to exit, or until a signal is delivered whose action is to terminate the current process or to call a signal handling function. If the process has already exited (i.e. it is a "zombie" process) then wait() returns immediately. Waiting for the child process causes all its system resources to be freed. yes bestie, we do the waiting so the zombie gets reaped, it's called closure 🧟‍♀️✨

error() will return EINTR if wait() is interrupted by a signal.

Parameters

  • nohang — true to return immediately if the process has not exited.

Returns

  • 1 if the process has exited and wait() has not yet been called. 0 if nohang is true and the process has not exited yet. -1 if no process has been started or if an error occurs, in which case the error can be found using error().
References: is_open(), and redi::pstreams::pstdin. Referenced by close(), exited(), and open().

wpipe() 🚿

template<typename C, typename T> pstreams::fd_type & redi::basic_pstreambuf< C, T >::wpipe () [inline],  [protected]

Return the file descriptor for the output pipe.

Returns

  • a reference to the output file descriptor
Referenced by write().

write() ✍️

template<typename C, typename T> std::streamsize redi::basic_pstreambuf< C, T >::write (const char_type * s, std::streamsize n) [inline],  [protected]

Insert a sequence of characters into the pipe. Writes up to n characters to the pipe from the buffer s.

Parameters

  • s — character buffer.
  • n — buffer length.

Returns

  • the number of characters written.
References: wpipe(), and write(). Referenced by empty_buffer(), open(), and write().

xsputn() ✨

template<typename C, typename T> std::streamsize redi::basic_pstreambuf< C, T >::xsputn (const char_type * s, std::streamsize n) [protected]

Insert multiple characters into the pipe.

Parameters

  • s — character buffer.
  • n — buffer length.

Returns

  • the number of characters written.
References: empty_buffer().

close_fd() 🧹

template<typename CharT, typename Traits = std::char_traits<CharT>> void close_fd (pstreams::fd_type & fd) [related]

Helper function to close a file descriptor. Inspects fd and calls close(3) if it has a non-negative value. very "if it's real, we close it" of it 💅

Parameters

  • fd — a file descriptor.

close_fd_array() 🧺

template<int N> void close_fd_array (pstreams::fd_type(&) fds[N]) [related]

Helper function to close an array of file descriptors. Calls close_fd() on each member of the array. The length of the array is determined automatically by template argument deduction to avoid errors. no manual counting required, the compiler does the math for you, we love a self-sufficient icon 😌

Parameters

  • fds — an array of file descriptors.

✍️ Author

Generated automatically by Doxygen for PStreams from the source code.

and that's a wrap on part two, bestie 🎀 the footer is just the man page name tag for redi::basi...T, Traits >(3) sitting pretty next to PStreams, stamped with whatever date Doxygen felt like when it spat this out. no cap, you just read the whole thing 💖✨🦋

📦 where this page comes from