Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FBB::Pipe(3bobcat)	System Level Communication Pipe	    FBB::Pipe(3bobcat)

NAME
       FBB::Pipe - Defines a system level communication	pipe

SYNOPSIS
       #include	<bobcat/pipe>
       Linking option: -lbobcat

DESCRIPTION
       FBB::Pipe objects may be	used to	construct a pipe. Pipe objects offer a
       simple interface	to the reading and writing ends	of pipes. Pipe objects
       are object-wrappers around the pipe(2) system call.

       A  Pipe which is	created	just before a program forks can	be used	to set
       up a line of communication between the parent and child process.	Infor-
       mation  which  is  written  by the child	process	to its standard	output
       stream can be redirected	to the writing end  of	the  pipe  (using  the
       writtenBy  member). The information appearing at	the reading end	of the
       pipe can	then be	extracted using, e.g., an IFdStream  object,  initial-
       ized with the Pipe's reading file descriptor, or	the reading end	of the
       pipe can	be redirected to an existing stream whose file	descriptor  is
       known, like cin (which uses the STDIN_FILENO file descriptor).

       When  a	Pipe  object  goes out of scope, no close(2) operation is per-
       formed on the pipe's file descriptors. After setting up the pipe	 using
       the  Pipe's member functions and	passing	the Pipe's file	descriptors to
       code that uses the Pipe's descriptors, the Pipe object  could  in  fact
       safely  be destroyed. If	the pipe should	be closed at destruction time,
       a class could be	derived	from Pipe(3bobcat), whose destructor  performs
       the required closing-operation.

NAMESPACE
       FBB
       All  constructors,  members,  operators	and manipulators, mentioned in
       this man-page, are defined in the namespace FBB.

INHERITS FROM
       -

CONSTRUCTORS
       o      Pipe():
	      The default Pipe constructor constructs a	 basic	pipe,  calling
	      pipe(2).

	      This  constructor	 throws	 an Exception exception	if the default
	      Pipe constructor did not properly	complete.  The	thrown	Excep-
	      tion  object's which() member shows the system's errno value set
	      by the failing pipe(2) function.

       o      Pipe(int const *fd):
	      This constructor expects two file	descriptors, which already de-
	      fine  a  pipe,  stored  at fd. Following the construction	of the
	      Pipe object the array at by fd is	no longer used by the Pipe ob-
	      ject.  The copy constructor is available.

MEMBER FUNCTIONS
       o      int readFd() const:
	      Returns the pipe's file descriptor that is used for reading

       o      void readFrom(int	filedescriptor):
	      Sets up redirection from the internal read filedescriptor	to the
	      given filedescriptor: information	written	to  the	 write-end  of
	      the pipe may be retrieved	by extracting the information from the
	      stream that is associated	with the  indicated  file  descriptor.
	      E.g.,  after  the	 call  readFrom(STDIN_FILENO) information  in-
	      serted into the write-end	of the pipe can	be retrieved from cin.

       o      void readFrom(int	const *filedescriptors,	size_t n):
	      Sets up redirection from the internal read filedescriptor	to the
	      given  filedescriptors: information is read from the Pipe	object
	      when reading from	any of the n provided filedescriptors (experi-
	      mental).

       o      int readOnly():
	      Closes  the  writing  end	of the pipe, returns the reading end's
	      file descriptor. This member can be used,	e.g., to construct  an
	      IFdStream	 object	 to  extract  the information that is inserted
	      into the write-end of the	pipe.

       o      void verify() const:
	      Obsoleted, can safely be removed from source files.

       o      int writeFd() const:
	      Returns the pipe's file descriptor that is used for writing.

       o      void writtenBy(int filedescriptor):
	      Sets up redirection from the internal  write  filedescriptor  to
	      the  given  filedescriptor:  information is  written to the Pipe
	      object when writing to the provided filedescriptor. E.g.,	 after
	      the  call	writtenBy(STDOUT_FILENO) information sent to the stan-
	      dard output stream (by either cout or by a  child	 process  (cf.
	      exec(3)))	is inserted into the write-end of the pipe.

       o      void writtenBy(int const *filedescriptors, size_t	n):
	      Sets  up	redirection  from the internal write filedescriptor to
	      the given	filedescriptors:  information  is  inserted  into  the
	      write-end	 of the	Pipe object when writing to each of the	n pro-
	      vided filedescriptors.  E.g., when passing an array of  two  int
	      values, respectively equal to STDOUT_FILENO and STDERR_FILENO to
	      this member, all information which is  thereafter	 sent  to  the
	      standard	output or error	streams	is inserted into the write-end
	      of the pipe.

       o      int writeOnly():
	      Closes the reading end of	the pipe, returns  the	writing	 end's
	      file descriptor.

PROTECTED ENUMERATION
       The RW protected	enumeration has	the following elements:

       o      READ:
	      The  index  in  d_fd[]  (see  below)  of the element holding the
	      pipe's reading file descriptor;

       o      WRITE:
	      The index	in d_fd[] (see	below)	of  the	 element  holding  the
	      pipe's writing file descriptor

PROTECTED DATA
       o      int d_fd[2]:
	      The  array holding the pipe's file descriptors. The READ element
	      contains the pipe's reading file descriptor, the	WRITE  element
	      contains the pipe's writing file descriptor,

EXAMPLE
	   #include <bobcat/pipe>
	   #include <sys/types.h>
	   #include <sys/wait.h>
	   #include <unistd.h>
	   #include <iostream>
	   #include <string>

	   using namespace std;
	   using namespace FBB;

	   int main()
	   {
	       Pipe p;			       // construct a pipe

	       cout << "Read file descriptor: "	<< p.getReadFd() << endl;
	       cout << "Write file descriptor: " << p.getWriteFd() << endl;

	       int pid = fork();

	       if (pid == -1)
		   return 1;

	       if (!pid)		       //child
	       {
		   p.readFrom(STDIN_FILENO);   // read what goes into the pipe

		   string s;

		   getline(cin,	s);
		   cout	<< "CHILD: Got `" << s << "'" << endl;

		   getline(cin,	s);
		   cout	<< "CHILD: Got `" << s << "'" << endl;

		   return 0;
	       }

	       p.writtenBy(STDOUT_FILENO);	// write to the	pipe via cout

	       cout << "first line" << endl;
	       cout << "second line" <<	endl;

	       waitpid(pid, 0, 0);

	       return 0;
	   }

       See also	the 2nd	example	at fork(3bobcat)

FILES
       bobcat/pipe - defines the class interface

SEE ALSO
       bobcat(7), fork(3bobcat), pipe(2), mkfifo(3)

BUGS
       Note  that  when	 the  pipe goes	out of scope, no close(2) operation is
       performed on the	pipe's ends. If	the pipe should	be closed by the desc-
       tructor,	 derive	 a class from Pipe(3bobcat), whose destructor performs
       the required closing-operation.

DISTRIBUTION FILES
       o      bobcat_3.25.01-x.dsc: detached signature;

       o      bobcat_3.25.01-x.tar.gz: source archive;

       o      bobcat_3.25.01-x_i386.changes: change log;

       o      libbobcat1_3.25.01-x_*.deb:  debian  package  holding  the   li-
	      braries;

       o      libbobcat1-dev_3.25.01-x_*.deb:  debian  package holding the li-
	      braries, headers and manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT
       Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.

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

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

libbobcat-dev_3.25.01-x.tar.gz	   2005-2015		    FBB::Pipe(3bobcat)

NAME | SYNOPSIS | DESCRIPTION | NAMESPACE | INHERITS FROM | CONSTRUCTORS | MEMBER FUNCTIONS | PROTECTED ENUMERATION | PROTECTED DATA | EXAMPLE | FILES | SEE ALSO | BUGS | DISTRIBUTION FILES | BOBCAT | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pipe&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help