popen()

Execute a command, creating a pipe to it

Synopsis:

#include <stdio.h>

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

Arguments:

command: The command that you want to execute.
mode: The I/O mode for the pipe, which must be "r" or "w"; see below.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Note: This function is in libc.a, but not in libc.so (in order to save space).

Description:

The popen() function executes the command specified by command and creates a pipe between the calling process and the executed command.

Depending on the mode argument, you can use the returned stream pointer to read from or write to the pipe.

The executed command has the same environment as its parents. The command is started as follows:

spawnlp (P_NOWAIT, shell_command, shell_command, 
         "-c", command, (char* )NULL );

where shell_command is the command specified by the SHELL environment variable (if it exists), or the sh utility.

The mode argument to popen() is a string that specifies an I/O mode for the pipe:

If mode is "r", then when the child process is started:
- Its file descriptor, STDOUT_FILENO, is the writable end of the pipe.
- The fileno( stream ) in the calling process is the readable end of the pipe, where stream is the stream pointer returned by popen().
If mode is "w", then when the child process is started:
- Its file descriptor, STDIN_FILENO, is the readable end of the pipe.
- The fileno( stream ) in the calling process is the writable end of the pipe, where stream is the stream pointer return by popen().
If mode is any other value, popen() sets errno to EINVAL.

Note: Use pclose() to close a stream that you used popen() to open.

Returns:

A non-NULL stream pointer on successful completion. If popen() is unable to create either the pipe or the subprocess, it returns a NULL stream pointer and sets errno.

Errors:

EINVAL: The mode argument is invalid.
ENOSYS: There's no pipe manager running.

The popen() function may also set errno values as described by the pipe() and spawnl() functions.

Examples:

/*
 * upper:  executes a given program, converting all input
 *      to upper case.
 */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include <unistd.h>
#include <limits.h>

char   buffer[_POSIX_ARG_MAX];

int main( int argc, char** argv )
  {
    int  i;
    int  c;
    FILE* f;

    for( i = 1; i < argc; i++ ) {
      strcat( buffer, argv[i] );
      strcat( buffer, " " );
    }
    if( ( f = popen( buffer, "w" ) ) == NULL ) {
      perror( "popen" );
      return EXIT_FAILURE;
    }
    while( ( c = getchar() ) != EOF ) {
      if( islower( c ) )
        c = toupper( c );
      putc( c, f );
    }
    pclose( f );
    return EXIT_SUCCESS;
  }

Classification:

POSIX 1003.1

Safety:
Cancellation point	Yes
Interrupt handler	No
Signal handler	No
Thread	Yes