FBB::Proc(3bobcat)

📦
version 6.15.01 · 4 versions
, in ubuntu stonking

🌸 FBB::Proc(3bobcat) — running child processes 💖

ok bestie, welcome to FBB::Proc, a page from the 3bobcat manual, and honestly? she's that girl. this is the class that runs external programs for you from C++, and she does it with an extensive interface. let's get into it ✨

🎀 NAME 🎀

FBB::Proc — runs external programs. that's it, that's the job. iconic behavior fr fr.

✨ SYNOPSIS ✨

#include <bobcat/proc>

Linking option: -lbobcat

like, don't forget that link flag, it's giving "mandatory" 💅

💖 DESCRIPTION 💖

okay so. FBB::Proc is an alternative to the FBB::Process class. she offers an extensive interface for calling external programs and/or scripts from a C++ program — the so-called child processes. the whole vibe is an easy-to-use, stream-based interface so you can talk to a child process's standard input, output and error streams like it's nothing. obsessed.

objects of the class Proc use standard process-executing functions, like the members of the execl(2) family or sh(1), to execute child processes. so a child process can literally be an executable program or a shell script. no cap.

the standard input, output and error streams of child processes may be accessed through their Proc parent objects. input that the child process expects can be inserted into Proc objects. standard output and standard error generated by the child process are inserted into — and further handled by — std::ostream objects, by default std::cout and std::cerr.

when you're using (output) redirection while executing child processes with the USE_SHELL path specification (peep below for the path and IOMode specs), you should normally specify the IGNORE_COUT IOMode (and possibly IGNORE_CERR too). check the ENUMERATIONS section for what the IOMode enumeration actually means 🫶

Proc objects can be reused over and over to run the same or different child processes. before the next child process starts, the Proc object makes sure its currently active child process is done. alternatively, a currently active child process ends if:

  • the Proc object goes out of scope,
  • the allotted execution time of the child process has passed,
  • a new process is started using Proc's assignment operator, or
  • its stop member is called.

otherwise, child processes just keep going until completion when you call finish, or — if the child process reads its standard input stream — when the eoi manipulator is inserted into the Proc object.

programs called as child processes may be specified when constructing a Proc object, or by using Proc's setCommand member. heads up bestie: Proc constructors (and the setCommand member) don't start child processes. to actually start them you must use the start members or the assignment operator. periodt.

child processes may receive info at their standard input streams through information inserted into Proc objects. in those cases, Proc objects have to inform their child processes that they've received all input. for this, the eoi manipulator can be inserted into Proc objects, or Proc's finish member can be called ✨

if information sent to the child isn't fully processed by the child process, then the operating system issues a Broken pipe message, indicating that information in a pipe was lost — which ends the program 😭. the Proc class's member pipeSignal can be used to suppress that Broken pipe message.

arguments passed to child processes may be surrounded by double or single quotes:

  • arguments surrounded by double quotes have their double quotes removed, while interpreting any escape-sequences that may have been used within.
  • arguments surrounded by single quotes have their single quotes removed, while accepting their content as-is.
  • plus, unquoted escape-sequences may be specified: those escape sequences are evaluated and replaced by their intended characters (e.g., \100 is converted to @).

a full command specification may also be surrounded by backtics (`-characters). these backtick characters are removed by the Proc object when the command starts. (` as punctuation, we love to see it 🦋)

child processes may be allotted a limited amount of time (in seconds) to complete. by default no time limit is imposed upon child processes. if a time limit is specified, then the child process — if it's still running after the specified number of seconds — is ended by sending it a SIGTERM signal, followed by a SIGKILL signal (cf. signal(7)). yeah, she doesn't play. 💀

by default, the standard input, output and error streams of child processes are handled by their Proc parent processes: info inserted into the Proc object is forwarded to the child process's standard input stream, and info sent by the child process to its standard output and error streams is either forwarded to the corresponding streams of the parent process, or processed by streams configured by the Proc object.

multiple Proc processes can be combined using the pipe operator (i.e., the | operator). when used, the standard output stream of the left-hand side (lhs) Proc object becomes the standard input stream of the right-hand side (rhs) Proc object. since the Proc objects start their own child processes, this effectively boils down to the output of the lhs's child process being used as the input of the rhs's child process. the leftmost Proc object may also read its input (using the pipe operator) from an istream object, or from a file whose name (path) is specified as the most lhs argument of a pipe expression. likewise, the rightmost Proc object may pipe its standard output to an existing ostream object, or to a file whose name (path) is specified as the most rhs argument of a pipe expression. it's giving pipelines and honestly? slay 🌈

Proc objects use Pipe objects (cf. pipe(3bobcat)) for communication with their child processes. to make sure those pipes are properly closed, you should use the members waitForChild, stop, or the eoi manipulator. once a Proc object ceases to exist, pipes to its child process are also closed.

🧚 NAMESPACE 🧚

FBB

all constructors, members, operators and manipulators mentioned in this man-page are defined in the namespace FBB. iykyk 💜

👑 INHERITS FROM 👑

  • FBB::Fork(3bobcat) (private)
  • std::ostream

🌟 ENUMERATIONS 🌟

the following enumerations are defined by the Proc class:

enum ProcType

the enum ProcType defines how a child proc is started or located. its values are specified at constructor-time or through the setProcType member. this enumeration defines the following symbolic constants:

  • NO_PATH: the program specified as child proc is started as specified, without searching the elements of the PATH environment variable.
  • USE_PATH: the elements of the PATH environment variable are used when locating the program specified as child proc.
  • USE_SHELL: the program specified as child proc is called using /bin/sh -c. when (output) redirection is used with the specified command, the IGNORE_COUT IOMode (and possibly also the IGNORE_CERR IOMode) should be specified.

enum IOMode

values of the enum IOMode are used to define which of the child proc's standard streams can be accessed through the Proc object. its symbolic constants may be combined using the bit_or operator. by default CIN | COUT | CERR is used (see below).

IOMode arguments may be combined using bit-or operators.

the following symbolic constants are available:

  • ALL: shortcut for CIN | COUT | CERR.
  • CIN: information inserted into the Proc object is forwarded to its child proc. if this is not required then CIN should not be specified.
  • CERR: information written by the child process to its standard error stream is made available as Proc's standard error stream. if this is not required then CERR should not be specified.
  • COUT: information written by the child process to its standard output stream is made available as Proc's standard output stream. if this is not required then CERR should not be specified.
  • IGNORE_CERR: information written by the child proc to its standard error stream is ignored (i.e., not made available). an std::invalid_argument exception is thrown if this mode is specified in combination with CERR, MERGE_COUT_CERR, and/or REPLACE.
  • IGNORE_COUT: information written by the child proc to its standard output stream is ignored. an std::invalid_argument exception is thrown if this mode is specified in combination with COUT, MERGE_COUT_CERR and/or REPLACE.
  • IGNORE_COUT_CERR: shortcut for IGNORE_CERR | IGNORE_COUT.
  • MERGE_COUT_CERR: information written by the child process to its standard output and standard error streams is made available at the Proc object's standard output stream. an std::invalid_argument exception is thrown if this mode is specified in combination with COUT, CERR, IGNORE_COUT, IGNORE_CERR or REPLACE.
  • NONE: the Proc object does not insert information into the standard input streams of its child process, and information written by the child process to its standard output or error streams is not forwarded to the Proc object. instead, the child process processes its standard streams by itself. when this mode is specified in combination with other IOMode values it is silently ignored.
  • REPLACE: when starting a child proc (see below at the member start) the current process (i.e., the program defining the Proc object) is replaced by the child process, inheriting the current process's standard input and output streams. if this mode is specified in combination with any other IOMode (except for NONE, see below) an std::invalid_argument exception is thrown.
okay so those std::invalid_argument combos? not a vibe. don't do them. 🙈

🌸 CONSTRUCTOR 🌸

note that child processes are not started automatically following the construction of Proc objects. a start member or the assignment operator (see below) is used to start child processes.

once a Proc object has been constructed, its parameters can be changed using set-member functions or start members.

  • explicit Proc(std::string const &command = "", IOMode mode = ALL, ProcType type = NO_PATH, size_t bufSize = 200, size_t timeLimit = 0, bool pipeSignal = true): the parameter bufSize defines the size of the streambuf buffers used by the Proc object. the timeLimit specifies the maximum execution time of a child process in seconds; when timeLimit == 0 no execution time limit is used. when pipeSignal == true, incomplete processing of information sent to or read from the child process results in a Broken pipe exception, terminating the program. when specifying false the Broken pipe exception is suppressed, and the input and/or output streams do not have to be completely processed (see also pipeSignal's description).

copy and move constructors (and assignment operators) are not available. she's exclusive like that 💅

bestie, that's not even all of it — more of this page is coming right up, don't go anywhere 🦋

💅 OVERLOADED OPERATORS 💅

okay bestie, this is where the Proc girlies shine — the operators. buckle up 🎀

  • Proc &operator<<(Type value) — this one inserts value right into the child's standard input stream. so like, the child proc reads value from its own stdin, periodt. literally any type that can be inserted into an ostream can be inserted into a Proc object. if the child proc has already terminated? nothing happens, it's giving ghosted 👻. manipulators like std::endl are supported too, slay. ⚠️ the behavior of this operator is undefined when IOMode CIN has not been specified — so don't do that, iykyk.
  • Proc &operator+=(std::string const &) — this adds the std::string you hand it to the currently defined command specification of the Proc object. and bestie, hear me: the member operator+= does not sneak a separating blank space between the currently stored command specification and the text you're appending. it merely adds its right-hand side string to the command stored so far. it does not affect a currently running child process either. no cap. 💅
  • int operator=(std::string const &cmd) — this defines cmd as the stored command in a Proc object, and thereupon starts cmd as its child process. but first — before starting the child process — a possibly active child process is first stopped by calling stop. it returns stop's return value. and immediately after calling stop, the new command (cmd) is started. if ending and restarting another command should be separate actions, then use finish or stop, followed by setCommand, followed by calling an appropriate overloaded version of the member start. ✨
  • Return operator|(Proc &lhs, Proc &rhs) — the piping operator, she's iconic. information sent by lhs to its standard output is used as the standard input of the rhs's child process. the Return value is rhs if the expression is followed by another pipe-operator, or it is void.
  • Return operator|(std::istream &in, Proc &proc) — more piping. information read from in is read by proc's child process. the Return value is proc if the expression is followed by another pipe-operator, or it is void.
  • Return operator|(std::string const &fname, Proc &proc) — piping again 🦋. information in the file whose file (path) name is fname is read by proc's child process. the Return value is proc if the expression is followed by another pipe-operator, or it is void.
  • void operator|(Proc &proc, std::ostream &out) — piping, the sequel 💖. information sent by proc's child process to its standard output stream is written to out.
  • void operator|(Proc &proc, std::string &fname) — piping one last time. information sent by proc's child process to its standard output stream is written to the file whose file (path) name is fname.

the pipe (|) operator mimics the pipe-operator supported by most command-shell programs, and bestie, do not confuse it with the bit-or operator, that's a different vibe entirely 🙈. the pipe operator allows constructions like

p1 | p2 | p3            // piping 3 Proc objects
cin | p1 | p2 | cout    // p1 reads cin, p2 writes cout
inName | p1 | outName   // inName: file name of the file
                        // read by p1, outName: file name
                        // of the file written by p1

when using the pipe operator, Proc objects reading input automatically specify their CIN modes, while Proc objects writing their standard output automatically specify their COUT modes. and following the pipe-expression, the IOMode specifications which were specified before the pipe-expression are restored. the way that works is lowkey so satisfying 🫶

🌸 MEMBERS 🌸

  • bool active() — if the child proc is currently running, true is returned, and false if not. simple as.
  • void cerrMode(char const *lab) const — the label lab, followed by a textual representation of the currently configured IOMode, is inserted into std::cerr.
  • void cerrPipes(char const *lab) const — the text Proc, followed by the Proc's id, followed by label lab, followed by the currently active read and write file descriptors of the pipes currently used by the Proc object, are inserted into std::cerr. it's giving diagnostics 💅
  • std::string const &cmd() const — the currently specified child-process starting command is returned.
  • int exitStatus() const — the last child-process's exit-status is returned. if a child process is currently running, or if no child process has yet been started, -1 is returned.
  • int finish() — waits until a currently active child process has ended, and returns its exit status. if the child process isn't currently running, -1 is returned. bye bestie, see you when you're done 😭
  • IOMode ioMode() const — the IOMode currently used by the Proc object is returned.
  • std::string mode() const — the IOMode currently used by the Proc object is returned as a text-string.
  • int pid() const — the child process's process-id is returned. ⚠️ the returned value is undefined if no child process has yet been started. if the child process has already completed, the last child process's id is returned.
  • void pipeSignal(bool on) — when incompletely forwarding information to a child process or incompletely reading information from a child process, a Broken pipe may result, ending the currently running program. to avoid this, pipeSignal(false) can be called. to reactivate recognizing broken pipes, pipeSignal(true) can be called. after using pipeSignal(false), failing insertions into a Proc object result in its member good returning false, and its members bad and fail returning true. 🚨
  • size_t procIdx() const — every constructed Proc object receives its own construction-order index. the first Proc object constructed in a program gets index value 0. main character energy, obviously 👑
  • ProcType procType() const — the ProcType used when starting child processes is returned.
  • void setBufSize(size_t bufSize) — the stream buffer size in bytes used by streams communicating with child processes is set to bufSize. a zero byte buffer size is silently changed into one.
  • void setCommand(std::string const &cmd) — the (initial part of a) child process command specification is set to cmd. after calling this, member operator+= can be used to append additional text to the command specification.
  • void setIOMode(IOMode mode) — the IOMode used when calling child processes is set to mode. note that pipe-expressions may modify the mode of Proc objects while the pipe-expression is executed. for details, see the end of the OVERLOADED OPERATORS section ✨
  • void setProcType(ProcType type) — the ProcType used when starting child processes is set to type.
  • void setTimeLimit(size_t timeLimit) — the execution time limit of child processes is set to timeLimit (in seconds). no time limit is used when timeLimit 0 is specified. the time limit set by setTimeLimit is used when starting the next child process. when calling setTimeLimit, then pipeSignal(timeLimit == 0) is automatically called. if that's not intended, then explicitly call pipeSignal after calling setTimeLimit. sneaky little side effect, highkey 😳
  • void start(size_t timeLimit, IOMode mode = ALL, ProcType type = NO_PATH, size_t bufSize = 200) — the currently specified command is started using the specified timeLimit, IOMode, ProcType and bufSize arguments. the start members do not alter the currently configured default values of their arguments.

if a child process is still active when start is called, it first calls stop to end the currently running child process.

  • void start(IOMode mode, ProcType type = NO_PATH, size_t bufSize = 200) — same as the previous start member, but using the currently configured timeLimit and requiring the specification of the IOMode to use.
  • void start() — same as the first start member, but using the currently configured timeLimit, IOMode, ProcType and bufSize values. it just knows what you want 💅
  • int stop() — a currently active child process is ended by calling Fork::endChild (see also fork(3bobcat)).
  • void system(size_t timeLimit, IOMode mode = ALL, size_t bufSize = 200) — the currently stored command is executed as a command of sh(1), using the specified process-arguments.
  • void system(IOMode mode = ALL, size_t bufSize = 200) — same as the previous system command, but using the default timeLimit specification.
  • size_t timeLimit() const — the currently configured execution time limit of Proc's child process is returned. the return value zero indicates that no time limit is used.
  • void useErr(std::ostream &out) — the standard error output produced by the child process is sent to out. if the Proc object had specified IGNORE_CERR, then that IOMode is unset, and the CERR mode is set.
  • void useErr(std::string const &fname) — same as the previous member, but the child's standard error output is written to the file (path) fname.
  • void useMerge(std::ostream &out) — the standard output and standard error output produced by the child process is sent to out. if the Proc object had specified CERR, COUT, IGNORE_CERR, or IGNORE_COUT, then those IOModes are unset, and the MERGE_COUT_CERR mode is set. two streams, one vibe 🌈
  • void useMerge(std::string const &fname) — same as the previous member, but the child's standard output and standard error output is written to the file (path) fname.
  • void useOut(std::ostream &out) — the standard output produced by the child process is sent to out. if the Proc object had specified IGNORE_COUT, then that IOMode is unset, and the COUT mode is set.
  • void useOut(std::string const &fname) — same as the previous member, but the child's standard output is written to the file (path) fname.
  • int waitForChild() — this member calls the identically named member from the class FBB::Fork, waiting for a child process to end. when calling finish or using pipe-expressions, waitForChild is automatically called. no need to chase it down yourself, bestie 🫶

🌈 EXAMPLES 🌈

okay bestie, every single one of these starts with the same lil preamble, no exceptions:

#include <iostream>
#include <bobcat/proc>

using namespace std;
using namespace FBB;

✨ Example one — a child program that only produces output. Its child proc is literally just /bin/ls:

int main()
{
    Proc proc("/bin/ls -Fla", Proc::COUT);

    proc.start();
}

✨ Example two — a child program that gets a limited amount of execution time. Lines you type at the keyboard get echoed to the standard output stream for at most 5 seconds:

int main()
{
    Proc proc("/bin/cat", Proc::CIN | Proc::COUT);
    proc.setTimeLimit(5);

    proc.start();

    while (true)
    {
        cout << "? ";
        string line;
        if (not getline(cin, line))
            return 0;

        proc << line << endl;           // to /bin/cat

        if (not proc.good())
        {
            cout << "child time limit exceeded\n";
            break;
        }
    }

    cout << "/bin/cat time limit of 5 seconds reached: child proc ended\n";
}

✨ Example three — piping, the moment you've all been waiting for. Info sitting at the program's standard input gets piped to a second Proc object, and that one writes its standard output to the program's standard output stream:

int main()
{
    Proc proc1{ "/bin/cat" };
    Proc proc2{ "/bin/cat" };

    cin | proc1 | proc2;            // By default piping to cout. To do that
                                    // explicitly use ’... | proc2 | cout’
}

(yeah, by default it pipes to cout. if you wanna say that out loud, go ’... | proc2 | cout’ 💅)

🎀 FILES 🎀

  • bobcat/proc — defines the class interface

👀 SEE ALSO 👀

bobcat(7), execle(3), fork(3bobcat), process(3bobcat), ostream(3fork), sh(1)

💀 BUGS 💀

(empty. truly nothing to report. the bugs section said nothing and honestly? iconic of it.)

📦 BOBCAT PROJECT FILES 📦

Debian Bobcat project files:

  • libbobcat6 — debian package containing the shared library, changelog and copyright note;
  • libbobcat-dev — debian package containing the static library, headers, manual pages, and developer info;

👑 BOBCAT 👑

Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’. 🦋

This is free software, distributed under the terms of the GNU General Public License (GPL).

🫶 AUTHOR 🫶

Frank B. Brokken (f.b.brokken@rug.nl).

k that's the whole page bestie, you're officially a FBB::Proc girlie now 💅✨ it's from libbobcat-dev_6.15.01, dated 2005-2026, and yeah — that footer is literally the cover of the book, periodt 🎀 go forth and fork responsibly 🌈

📦 where this page comes from