usr/src/man/man3c/popen.3c

   1 '\" te
   2 .\" Copyright (c) 2006, Sun Microsystems, Inc.   All Rights Reserved.
   3 .\" Copyright 1989 AT&T.
   4 .\" Portions Copyright (c) 1997, The Open Group. All Rights Reserved.
   5 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   6 .\" http://www.opengroup.org/bookstore/.
   7 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   8 .\"  This notice shall appear on any product containing this material.
   9 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  10 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  11 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  12 .TH POPEN 3C "Dec 14, 2006"
  13 .SH NAME
  14 popen, pclose \- initiate a pipe to or from a process
  15 .SH SYNOPSIS
  16 .LP
  17 .nf
  18 #include <stdio.h>
  19
  20 \fBFILE *\fR\fBpopen\fR(\fBconst char *\fR\fIcommand\fR, \fBconst char *\fR\fImode\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBint\fR \fBpclose\fR(\fBFILE *\fR\fIstream\fR);
  26 .fi
  27
  28 .SH DESCRIPTION
  29 .sp
  30 .LP
  31 The \fBpopen()\fR function creates a pipe between the calling program and the
  32 command to be executed.  The arguments to \fBpopen()\fR are pointers to
  33 null-terminated strings.  The \fIcommand\fR argument consists of a shell
  34 command line.  The \fImode\fR argument is an I/O mode, either \fBr\fR for
  35 reading or \fIw\fR for writing. The value returned is a stream pointer such
  36 that one can write to the standard input of the command, if the I/O mode is
  37 \fIw\fR, by writing to the file \fIstream\fR (see \fBIntro\fR(3)); and one can
  38 read from the standard output of the command, if the I/O mode is \fBr\fR, by
  39 reading from the file \fIstream\fR. Because open files are shared, a type
  40 \fBr\fR command may be used as an input filter and a type \fIw\fR as an output
  41 filter. A trailing \fBF\fR character can also be included in the \fImode\fR
  42 argument as described in \fBfopen\fR(3C) to enable extended FILE facility.
  43 .sp
  44 .LP
  45 The environment of the executed command will be as if a child process were
  46 created within the \fBpopen()\fR call using \fBfork\fR(2).  The child is
  47 created as if invoked with the call:
  48 .sp
  49 .LP
  50 \fBexecl("/usr/bin/sh", "sh", "\fR\fB-c\fR\fB", \fR\fIcommand\fR, \fB(char
  51 *)0);\fR
  52 .sp
  53 .LP
  54 The \fBpclose()\fR function closes a stream opened by \fBpopen()\fR by closing
  55 the pipe. It waits for the associated process to terminate and returns the
  56 termination status of the process running the command language interpreter.
  57 This is the value returned by \fBwaitpid\fR(3C). See \fBwait.h\fR(3HEAD) for
  58 more information on termination status. If, however, a call to \fBwaitpid()\fR
  59 with a \fIpid\fR argument equal to the process ID of the command line
  60 interpreter causes the termination status to be unavailable to \fBpclose()\fR,
  61 then \fBpclose()\fR returns \(mi1 with \fBerrno\fR set to \fBECHILD\fR to
  62 report this condition.
  63 .SH RETURN VALUES
  64 .sp
  65 .LP
  66 Upon successful completion, \fBpopen()\fR returns a pointer to an open stream
  67 that can be used to read or write to the pipe. Otherwise, it returns a null
  68 pointer and may set \fBerrno\fR to indicate the error.
  69 .sp
  70 .LP
  71 Upon successful completion, \fBpclose()\fR returns the termination status of
  72 the command language interpreter as returned by \fBwaitpid()\fR.  Otherwise, it
  73 returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error.
  74 .SH ERRORS
  75 .sp
  76 .LP
  77 The \fBpclose()\fR function will fail if:
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBECHILD\fR\fR
  82 .ad
  83 .RS 10n
  84 The status of the child process could not be obtained, as described in the
  85 DESCRIPTION.
  86 .RE
  87
  88 .sp
  89 .LP
  90 The \fBpopen()\fR function may fail if:
  91 .sp
  92 .ne 2
  93 .na
  94 \fB\fBEMFILE\fR\fR
  95 .ad
  96 .RS 10n
  97 There are currently \fBFOPEN_MAX\fR or \fBSTREAM_MAX\fR streams open in the
  98 calling process.
  99 .RE
 100
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fBEINVAL\fR\fR
 105 .ad
 106 .RS 10n
 107 The \fImode\fR argument is invalid.
 108 .RE
 109
 110 .sp
 111 .LP
 112 The \fBpopen()\fR function may also set \fBerrno\fR values as described by
 113 \fBfork\fR(2) or \fBpipe\fR(2).
 114 .SH USAGE
 115 .sp
 116 .LP
 117 If the original and \fBpopen()\fR processes concurrently read or write a common
 118 file, neither should use buffered I/O. Problems with an output filter may be
 119 forestalled by careful buffer flushing, for example, with \fBfflush()\fR (see
 120 \fBfclose\fR(3C)). A security hole exists through the \fBIFS\fR and \fBPATH\fR
 121 environment variables.  Full pathnames should be used (or \fBPATH\fR reset) and
 122 \fBIFS\fR should be set to space and tab (\fB" \et"\fR).
 123 .sp
 124 .LP
 125 Even if the process has established a signal handler for \fBSIGCHLD\fR, it will
 126 be called when the command terminates.  Even if another thread in the same
 127 process issues a \fBwait\fR(3C) call, it will interfere with the return value
 128 of \fBpclose()\fR. Even if the process's signal handler for \fBSIGCHLD\fR has
 129 been set to ignore the signal, there will be no effect on \fBpclose()\fR.
 130 .SH EXAMPLES
 131 .LP
 132 \fBExample 1 \fR\fBpopen()\fR example
 133 .sp
 134 .LP
 135 The following program will print on the standard output (see \fBstdio\fR(3C))
 136 the names of files in the current directory with a \fB\&.c\fR suffix.
 137
 138 .sp
 139 .in +2
 140 .nf
 141 #include <stdio.h>
 142 #include <stdlib.h>
 143 main(\|)
 144 {
 145         char *cmd = "/usr/bin/ls *.c";
 146         char buf[BUFSIZ];
 147         FILE *ptr;
 148
 149         if ((ptr = popen(cmd, "r")) != NULL) {
 150                 while (fgets(buf, BUFSIZ, ptr) != NULL)
 151                         (void) printf("%s", buf);
 152                 (void) pclose(ptr);
 153         }
 154         return 0;
 155 }
 156 .fi
 157 .in -2
 158
 159 .LP
 160 \fBExample 2 \fR\fBsystem()\fR replacement
 161 .sp
 162 .LP
 163 The following function can be used in a multithreaded process in place of the
 164 most common usage of the Unsafe \fBsystem\fR(3C) function:
 165
 166 .sp
 167 .in +2
 168 .nf
 169 int my_system(const char *cmd)
 170 {
 171         FILE *p;
 172
 173         if ((p = popen(cmd, "w")) == NULL)
 174                 return (-1);
 175         return (pclose(p));
 176 }
 177 .fi
 178 .in -2
 179
 180 .SH ATTRIBUTES
 181 .sp
 182 .LP
 183 See \fBattributes\fR(5) for descriptions of the following attributes:
 184 .sp
 185
 186 .sp
 187 .TS
 188 box;
 189 c | c
 190 l | l .
 191 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 192 _
 193 Interface Stability     See below.
 194 _
 195 MT-Level        Safe
 196 .TE
 197
 198 .sp
 199 .LP
 200 The \fBF\fR character in the \fImode\fR argument of \fBpopen()\fR is Evolving.
 201 In all other respects this function is Standard. The \fBpclose()\fR function is
 202 Standard.
 203 .SH SEE ALSO
 204 .sp
 205 .LP
 206 \fBksh\fR(1), \fBpipe\fR(2), \fBfclose\fR(3C), \fBfopen\fR(3C),
 207 \fBposix_spawn\fR(3C), \fBstdio\fR(3C), \fBsystem\fR(3C), \fBwait\fR(3C),
 208 \fBwaitpid\fR(3C), \fBwait.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5)