popen man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

POPEN(3C)							     POPEN(3C)

NAME
       popen, pclose - initiate a pipe to or from a process

SYNOPSIS
       #include <stdio.h>

       FILE *popen(const char *command, const char *mode);

       int pclose(FILE *stream);

DESCRIPTION
       The popen() function creates a pipe between the calling program and the
       command to be executed.	The arguments to popen() are pointers to null-
       terminated  strings.   The command argument consists of a shell command
       line.  The mode argument is an I/O mode, either r for reading or w  for
       writing. The value returned is a stream pointer such that one can write
       to the standard input of the command, if the I/O mode is w, by  writing
       to  the	file stream (see Intro(3)); and one can read from the standard
       output of the command, if the I/O mode is r, by reading from  the  file
       stream.	Because open files are shared, a type r command may be used as
       an input filter and a type w as an output filter. A trailing F  charac‐
       ter can also be included in the mode argument as described in fopen(3C)
       to enable extended FILE facility.

       The environment of the executed command will be as if a	child  process
       were  created within the popen() call using fork(2).  The child is cre‐
       ated as if invoked with the call:

       execl("/usr/bin/sh", "sh", "-c", command, (char *)0);

       The pclose() function closes a stream opened by popen() by closing  the
       pipe.  It waits for the associated process to terminate and returns the
       termination status of the process running the command  language	inter‐
       preter.	 This  is the value returned by waitpid(3C). See wait.h(3HEAD)
       for more information on termination status.  If,	 however,  a  call  to
       waitpid()  with	a  pid argument equal to the process ID of the command
       line interpreter causes the termination status  to  be  unavailable  to
       pclose(),  then	pclose() returns −1 with errno set to ECHILD to report
       this condition.

RETURN VALUES
       Upon successful completion, popen() returns a pointer to an open stream
       that  can be used to read or write to the pipe. Otherwise, it returns a
       null pointer and may set errno to indicate the error.

       Upon successful completion, pclose() returns the termination status  of
       the  command language interpreter as returned by waitpid().  Otherwise,
       it returns −1 and sets errno to indicate the error.

ERRORS
       The pclose() function will fail if:

       ECHILD
		 The status of the child process could	not  be	 obtained,  as
		 described in the DESCRIPTION.

       The popen() function may fail if:

       EMFILE
		 There	are  currently FOPEN_MAX or STREAM_MAX streams open in
		 the calling process.

       EINVAL
		 The mode argument is invalid.

       The popen() function may also set errno values as described by  fork(2)
       or pipe(2).

USAGE
       If the original and popen() processes concurrently read or write a com‐
       mon file, neither should use buffered I/O. Problems with an output fil‐
       ter  may	 be  forestalled by careful buffer flushing, for example, with
       fflush() (see fclose(3C)). A security hole exists through the  IFS  and
       PATH  environment  variables.   Full  pathnames should be used (or PATH
       reset) and IFS should be set to space and tab (" \t").

       Even if the process has established a signal handler  for  SIGCHLD,  it
       will  be called when the command terminates.  Even if another thread in
       the same process issues a wait(3C) call, it  will  interfere  with  the
       return  value  of  pclose().  Even  if the process's signal handler for
       SIGCHLD has been set to ignore the signal, there will be no  effect  on
       pclose().

EXAMPLES
       Example 1 popen() example

       The following program will print on the standard output (see stdio(3C))
       the names of files in the current directory with a .c suffix.

	 #include <stdio.h>
	 #include <stdlib.h>
	 main()
	 {
		 char *cmd = "/usr/bin/ls *.c";
		 char buf[BUFSIZ];
		 FILE *ptr;

		 if ((ptr = popen(cmd, "r")) != NULL) {
			 while (fgets(buf, BUFSIZ, ptr) != NULL)
				 (void) printf("%s", buf);
			 (void) pclose(ptr);
		 }
		 return 0;
	 }

       Example 2 system() replacement

       The following function can be used in a multithreaded process in	 place
       of the most common usage of the Unsafe system(3C) function:

	 int my_system(const char *cmd)
	 {
		 FILE *p;

		 if ((p = popen(cmd, "w")) == NULL)
			 return (-1);
		 return (pclose(p));
	 }

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ See below.      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ Safe	      │
       └────────────────────┴─────────────────┘

       The  F  character  in the mode argument of popen() is Evolving.	In all
       other respects this function is	Standard.  The	pclose()  function  is
       Standard.

SEE ALSO
       ksh(1),	pipe(2),  fclose(3C),  fopen(3C),  posix_spawn(3C), stdio(3C),
       system(3C), wait(3C), waitpid(3C), wait.h(3HEAD), attributes(5),	 stan‐
       dards(5)

				 Dec 14, 2006			     POPEN(3C)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net