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

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