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

FreeBSD Manual Pages

  
 
  

home | help
POPEN(3)		   Linux Programmer's Manual		      POPEN(3)

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

SYNOPSIS
       #include	<stdio.h>

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

       int pclose(FILE *stream);

   Feature Test	Macro Requirements for glibc (see feature_test_macros(7)):

       popen(),	pclose():
	   _POSIX_C_SOURCE >= 2	|| _XOPEN_SOURCE || _BSD_SOURCE	||
	   _SVID_SOURCE

DESCRIPTION
       The popen() function opens a process by creating	a pipe,	 forking,  and
       invoking	 the shell.  Since a pipe is by	definition unidirectional, the
       type argument may specify only reading or writing, not  both;  the  re-
       sulting stream is correspondingly read-only or write-only.

       The  command argument is	a pointer to a null-terminated string contain-
       ing a shell command line.  This command is passed to /bin/sh using  the
       -c  flag;  interpretation, if any, is performed by the shell.  The type
       argument	is a pointer to	a null-terminated string  which	 must  contain
       either the letter 'r' for reading or the	letter 'w' for writing.	 Since
       glibc 2.9, this argument	can additionally include the letter 'e', which
       causes  the close-on-exec flag (FD_CLOEXEC) to be set on	the underlying
       file descriptor;	see the	description of the O_CLOEXEC flag  in  open(2)
       for reasons why this may	be useful.

       The  return  value  from	popen()	is a normal standard I/O stream	in all
       respects	save  that  it	must  be  closed  with	pclose()  rather  than
       fclose(3).   Writing  to	 such a	stream writes to the standard input of
       the command; the	command's standard output is the same as that  of  the
       process	that called popen(), unless this is altered by the command it-
       self.  Conversely, reading from the stream reads	the command's standard
       output,	and  the  command's  standard input is the same	as that	of the
       process that called popen().

       Note that output	popen()	streams	are fully buffered by default.

       The pclose() function waits for the associated process to terminate and
       returns the exit	status of the command as returned by wait4(2).

RETURN VALUE
       The popen() function returns NULL if the	fork(2)	or pipe(2) calls fail,
       or if it	cannot allocate	memory.

       The pclose() function returns -1	if wait4(2) returns an error, or  some
       other error is detected.	 In the	event of an error, these functions set
       errno to	indicate the cause of the error.

ERRORS
       The popen() function does not set errno if memory allocation fails.  If
       the  underlying	fork(2)	 or pipe(2) fails, errno is set	appropriately.
       If the type argument is invalid,	and this condition is detected,	 errno
       is set to EINVAL.

       If pclose() cannot obtain the child status, errno is set	to ECHILD.

CONFORMING TO
       POSIX.1-2001.

       The 'e' value for type is a Linux extension.

BUGS
       Since  the  standard  input  of a command opened	for reading shares its
       seek offset with	the process  that  called  popen(),  if	 the  original
       process	has done a buffered read, the command's	input position may not
       be as expected.	Similarly, the output from a command opened for	 writ-
       ing  may	 become	 intermingled  with that of the	original process.  The
       latter can be avoided by	calling	fflush(3) before popen().

       Failure to execute the shell  is	 indistinguishable  from  the  shell's
       failure	to  execute command, or	an immediate exit of the command.  The
       only hint is an exit status of 127.

SEE ALSO
       sh(1), fork(2),	pipe(2),  wait4(2),  fclose(3),	 fflush(3),  fopen(3),
       stdio(3), system(3)

COLOPHON
       This  page  is  part of release 3.74 of the Linux man-pages project.  A
       description of the project, information about reporting bugs,  and  the
       latest	  version     of     this    page,    can    be	   found    at
       http://www.kernel.org/doc/man-pages/.

GNU				  2013-04-19			      POPEN(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | CONFORMING TO | BUGS | SEE ALSO | COLOPHON

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=popen&sektion=3&manpath=Debian+8.1.0>

home | help