1.0.5.30: small PCL re-organization
[sbcl/lichteblau.git] / src / code / run-program.lisp
blobea4fe4c97a47dbdacbd54ac953db925df7f1c605
1 ;;;; RUN-PROGRAM and friends, a facility for running Unix programs
2 ;;;; from inside SBCL
4 ;;;; This software is part of the SBCL system. See the README file for
5 ;;;; more information.
6 ;;;;
7 ;;;; This software is derived from the CMU CL system, which was
8 ;;;; written at Carnegie Mellon University and released into the
9 ;;;; public domain. The software is in the public domain and is
10 ;;;; provided with absolutely no warranty. See the COPYING and CREDITS
11 ;;;; files for more information.
13 (in-package "SB-IMPL") ;(SB-IMPL, not SB!IMPL, since we're built in warm load.)
15 ;;;; hacking the Unix environment
16 ;;;;
17 ;;;; In the original CMU CL code that LOAD-FOREIGN is derived from, the
18 ;;;; Unix environment (as in "man environ") was represented as an
19 ;;;; alist from keywords to strings, so that e.g. the Unix environment
20 ;;;; "SHELL=/bin/bash" "HOME=/root" "PAGER=less"
21 ;;;; was represented as
22 ;;;; ((:SHELL . "/bin/bash") (:HOME . "/root") (:PAGER "less"))
23 ;;;; This had a few problems in principle: the mapping into
24 ;;;; keyword symbols smashed the case of environment
25 ;;;; variables, and the whole mapping depended on the presence of
26 ;;;; #\= characters in the environment strings. In practice these
27 ;;;; problems weren't hugely important, since conventionally environment
28 ;;;; variables are uppercase strings followed by #\= followed by
29 ;;;; arbitrary data. However, since it's so manifestly not The Right
30 ;;;; Thing to make code which breaks unnecessarily on input which
31 ;;;; doesn't follow what is, after all, only a tradition, we've switched
32 ;;;; formats in SBCL, so that the fundamental environment list
33 ;;;; is just a list of strings, with a one-to-one-correspondence
34 ;;;; to the C-level representation. I.e., in the example above,
35 ;;;; the SBCL representation is
36 ;;;; '("SHELL=/bin/bash" "HOME=/root" "PAGER=less")
37 ;;;; CMU CL's implementation is currently supported to help with porting.
38 ;;;;
39 ;;;; It's not obvious that this code belongs here (instead of e.g. in
40 ;;;; unix.lisp), since it has only a weak logical connection with
41 ;;;; RUN-PROGRAM. However, physically it's convenient to put it here.
42 ;;;; It's not needed at cold init, so we *can* put it in this
43 ;;;; warm-loaded file. And by putting it in this warm-loaded file, we
44 ;;;; make it easy for it to get to the C-level 'environ' variable.
45 ;;;; which (at least in sbcl-0.6.10 on Red Hat Linux 6.2) is not
46 ;;;; visible at GENESIS time.
48 #-win32
49 (progn
50 (define-alien-routine wrapped-environ (* c-string))
51 (defun posix-environ ()
52 "Return the Unix environment (\"man environ\") as a list of SIMPLE-STRINGs."
53 (c-strings->string-list (wrapped-environ))))
55 ;#+win32 (sb-alien:define-alien-routine msvcrt-environ (* c-string))
57 ;;; Convert as best we can from an SBCL representation of a Unix
58 ;;; environment to a CMU CL representation.
59 ;;;
60 ;;; * (UNIX-ENVIRONMENT-CMUCL-FROM-SBCL '("Bletch=fub" "Noggin" "YES=No!"))
61 ;;; WARNING:
62 ;;; smashing case of "Bletch=fub" in conversion to CMU-CL-style
63 ;;; environment alist
64 ;;; WARNING:
65 ;;; no #\= in "Noggin", eliding it in CMU-CL-style environment alist
66 ;;; ((:BLETCH . "fub") (:YES . "No!"))
67 (defun unix-environment-cmucl-from-sbcl (sbcl)
68 (mapcan
69 (lambda (string)
70 (declare (type simple-base-string string))
71 (let ((=-pos (position #\= string :test #'equal)))
72 (if =-pos
73 (list
74 (let* ((key-as-string (subseq string 0 =-pos))
75 (key-as-upcase-string (string-upcase key-as-string))
76 (key (keywordicate key-as-upcase-string))
77 (val (subseq string (1+ =-pos))))
78 (unless (string= key-as-string key-as-upcase-string)
79 (warn "smashing case of ~S in conversion to CMU-CL-style ~
80 environment alist"
81 string))
82 (cons key val)))
83 (warn "no #\\= in ~S, eliding it in CMU-CL-style environment alist"
84 string))))
85 sbcl))
87 ;;; Convert from a CMU CL representation of a Unix environment to a
88 ;;; SBCL representation.
89 (defun unix-environment-sbcl-from-cmucl (cmucl)
90 (mapcar
91 (lambda (cons)
92 (destructuring-bind (key . val) cons
93 (declare (type keyword key) (type simple-base-string val))
94 (concatenate 'simple-base-string (symbol-name key) "=" val)))
95 cmucl))
97 ;;;; Import wait3(2) from Unix.
99 #-win32
100 (define-alien-routine ("wait3" c-wait3) sb-alien:int
101 (status sb-alien:int :out)
102 (options sb-alien:int)
103 (rusage sb-alien:int))
105 #-win32
106 (defun wait3 (&optional do-not-hang check-for-stopped)
107 #+sb-doc
108 "Return any available status information on child process. "
109 (multiple-value-bind (pid status)
110 (c-wait3 (logior (if do-not-hang
111 sb-unix:wnohang
113 (if check-for-stopped
114 sb-unix:wuntraced
117 (cond ((or (minusp pid)
118 (zerop pid))
119 nil)
120 ((eql (ldb (byte 8 0) status)
121 sb-unix:wstopped)
122 (values pid
123 :stopped
124 (ldb (byte 8 8) status)))
125 ((zerop (ldb (byte 7 0) status))
126 (values pid
127 :exited
128 (ldb (byte 8 8) status)))
130 (let ((signal (ldb (byte 7 0) status)))
131 (values pid
132 (if (position signal
133 #.(vector
134 sb-unix:sigstop
135 sb-unix:sigtstp
136 sb-unix:sigttin
137 sb-unix:sigttou))
138 :stopped
139 :signaled)
140 signal
141 (not (zerop (ldb (byte 1 7) status)))))))))
143 ;;;; process control stuff
144 (defvar *active-processes* nil
145 #+sb-doc
146 "List of process structures for all active processes.")
148 #-win32
149 (defvar *active-processes-lock*
150 (sb-thread:make-mutex :name "Lock for active processes."))
152 ;;; *ACTIVE-PROCESSES* can be accessed from multiple threads so a
153 ;;; mutex is needed. More importantly the sigchld signal handler also
154 ;;; accesses it, that's why we need without-interrupts.
155 (defmacro with-active-processes-lock (() &body body)
156 #-win32
157 `(without-interrupts
158 (sb-thread:with-mutex (*active-processes-lock*)
159 ,@body))
160 #+win32
161 `(progn ,@body))
163 (defstruct (process (:copier nil))
164 pid ; PID of child process
165 %status ; either :RUNNING, :STOPPED, :EXITED, or :SIGNALED
166 exit-code ; either exit code or signal
167 core-dumped ; T if a core image was dumped
168 #-win32 pty ; stream to child's pty, or NIL
169 input ; stream to child's input, or NIL
170 output ; stream from child's output, or NIL
171 error ; stream from child's error output, or NIL
172 status-hook ; closure to call when PROC changes status
173 plist ; a place for clients to stash things
174 cookie) ; list of the number of pipes from the subproc
176 (defmethod print-object ((process process) stream)
177 (print-unreadable-object (process stream :type t)
178 (let ((status (process-status process)))
179 (if (eq :exited status)
180 (format stream "~S ~S" status (process-exit-code process))
181 (format stream "~S ~S" (process-pid process) status)))
182 process))
184 #+sb-doc
185 (setf (documentation 'process-p 'function)
186 "T if OBJECT is a PROCESS, NIL otherwise.")
188 #+sb-doc
189 (setf (documentation 'process-pid 'function) "The pid of the child process.")
191 #+win32
192 (define-alien-routine ("GetExitCodeProcess@8" get-exit-code-process)
194 (handle unsigned) (exit-code unsigned :out))
196 (defun process-status (process)
197 #+sb-doc
198 "Return the current status of PROCESS. The result is one of :RUNNING,
199 :STOPPED, :EXITED, or :SIGNALED."
200 (get-processes-status-changes)
201 (process-%status process))
203 #+sb-doc
204 (setf (documentation 'process-exit-code 'function)
205 "The exit code or the signal of a stopped process.")
207 #+sb-doc
208 (setf (documentation 'process-core-dumped 'function)
209 "T if a core image was dumped by the process.")
211 #+sb-doc
212 (setf (documentation 'process-pty 'function)
213 "The pty stream of the process or NIL.")
215 #+sb-doc
216 (setf (documentation 'process-input 'function)
217 "The input stream of the process or NIL.")
219 #+sb-doc
220 (setf (documentation 'process-output 'function)
221 "The output stream of the process or NIL.")
223 #+sb-doc
224 (setf (documentation 'process-error 'function)
225 "The error stream of the process or NIL.")
227 #+sb-doc
228 (setf (documentation 'process-status-hook 'function)
229 "A function that is called when PROCESS changes its status.
230 The function is called with PROCESS as its only argument.")
232 #+sb-doc
233 (setf (documentation 'process-plist 'function)
234 "A place for clients to stash things.")
236 (defun process-wait (process &optional check-for-stopped)
237 #+sb-doc
238 "Wait for PROCESS to quit running for some reason. When
239 CHECK-FOR-STOPPED is T, also returns when PROCESS is stopped. Returns
240 PROCESS."
241 (loop
242 (case (process-status process)
243 (:running)
244 (:stopped
245 (when check-for-stopped
246 (return)))
248 (when (zerop (car (process-cookie process)))
249 (return))))
250 (sb-sys:serve-all-events 1))
251 process)
253 #-(or hpux win32)
254 ;;; Find the current foreground process group id.
255 (defun find-current-foreground-process (proc)
256 (with-alien ((result sb-alien:int))
257 (multiple-value-bind
258 (wonp error)
259 (sb-unix:unix-ioctl (sb-sys:fd-stream-fd (process-pty proc))
260 sb-unix:TIOCGPGRP
261 (alien-sap (sb-alien:addr result)))
262 (unless wonp
263 (error "TIOCPGRP ioctl failed: ~S" (strerror error)))
264 result))
265 (process-pid proc))
267 #-win32
268 (defun process-kill (process signal &optional (whom :pid))
269 #+sb-doc
270 "Hand SIGNAL to PROCESS. If WHOM is :PID, use the kill Unix system call. If
271 WHOM is :PROCESS-GROUP, use the killpg Unix system call. If WHOM is
272 :PTY-PROCESS-GROUP deliver the signal to whichever process group is
273 currently in the foreground."
274 (let ((pid (ecase whom
275 ((:pid :process-group)
276 (process-pid process))
277 (:pty-process-group
278 #-hpux
279 (find-current-foreground-process process)))))
280 (multiple-value-bind
281 (okay errno)
282 (case whom
283 #+hpux
284 (:pty-process-group
285 (sb-unix:unix-ioctl (sb-sys:fd-stream-fd (process-pty process))
286 sb-unix:TIOCSIGSEND
287 (sb-sys:int-sap
288 signal)))
289 ((:process-group #-hpux :pty-process-group)
290 (sb-unix:unix-killpg pid signal))
292 (sb-unix:unix-kill pid signal)))
293 (cond ((not okay)
294 (values nil errno))
295 ((and (eql pid (process-pid process))
296 (= signal sb-unix:sigcont))
297 (setf (process-%status process) :running)
298 (setf (process-exit-code process) nil)
299 (when (process-status-hook process)
300 (funcall (process-status-hook process) process))
303 t)))))
305 (defun process-alive-p (process)
306 #+sb-doc
307 "Return T if PROCESS is still alive, NIL otherwise."
308 (let ((status (process-status process)))
309 (if (or (eq status :running)
310 (eq status :stopped))
312 nil)))
314 (defun process-close (process)
315 #+sb-doc
316 "Close all streams connected to PROCESS and stop maintaining the
317 status slot."
318 (macrolet ((frob (stream abort)
319 `(when ,stream (close ,stream :abort ,abort))))
320 #-win32
321 (frob (process-pty process) t) ; Don't FLUSH-OUTPUT to dead process,
322 (frob (process-input process) t) ; .. 'cause it will generate SIGPIPE.
323 (frob (process-output process) nil)
324 (frob (process-error process) nil))
325 ;; FIXME: Given that the status-slot is no longer updated,
326 ;; maybe it should be set to :CLOSED, or similar?
327 (with-active-processes-lock ()
328 (setf *active-processes* (delete process *active-processes*)))
329 process)
331 ;;; the handler for SIGCHLD signals that RUN-PROGRAM establishes
332 #-win32
333 (defun sigchld-handler (ignore1 ignore2 ignore3)
334 (declare (ignore ignore1 ignore2 ignore3))
335 (get-processes-status-changes))
337 (defun get-processes-status-changes ()
338 #-win32
339 (loop
340 (multiple-value-bind (pid what code core)
341 (wait3 t t)
342 (unless pid
343 (return))
344 (let ((proc (with-active-processes-lock ()
345 (find pid *active-processes* :key #'process-pid))))
346 (when proc
347 (setf (process-%status proc) what)
348 (setf (process-exit-code proc) code)
349 (setf (process-core-dumped proc) core)
350 (when (process-status-hook proc)
351 (funcall (process-status-hook proc) proc))
352 (when (position what #(:exited :signaled))
353 (with-active-processes-lock ()
354 (setf *active-processes*
355 (delete proc *active-processes*))))))))
356 #+win32
357 (let (exited)
358 (with-active-processes-lock ()
359 (setf *active-processes*
360 (delete-if (lambda (proc)
361 (multiple-value-bind (ok code)
362 (get-exit-code-process (process-pid proc))
363 (when (and (plusp ok) (/= code 259))
364 (setf (process-%status proc) :exited
365 (process-exit-code proc) code)
366 (when (process-status-hook proc)
367 (push proc exited))
368 t)))
369 *active-processes*)))
370 ;; Can't call the hooks before all the processes have been deal
371 ;; with, as calling a hook may cause re-entry to
372 ;; GET-PROCESS-STATUS-CHANGES. That may be OK when using wait3,
373 ;; but in the Windows implementation is would be deeply bad.
374 (dolist (proc exited)
375 (let ((hook (process-status-hook proc)))
376 (when hook
377 (funcall hook proc))))))
379 ;;;; RUN-PROGRAM and close friends
381 ;;; list of file descriptors to close when RUN-PROGRAM exits due to an error
382 (defvar *close-on-error* nil)
384 ;;; list of file descriptors to close when RUN-PROGRAM returns in the parent
385 (defvar *close-in-parent* nil)
387 ;;; list of handlers installed by RUN-PROGRAM
388 #-win32
389 (defvar *handlers-installed* nil)
391 ;;; Find an unused pty. Return three values: the file descriptor for
392 ;;; the master side of the pty, the file descriptor for the slave side
393 ;;; of the pty, and the name of the tty device for the slave side.
394 #-win32
395 (progn
396 (define-alien-routine ptsname c-string (fd int))
397 (define-alien-routine grantpt boolean (fd int))
398 (define-alien-routine unlockpt boolean (fd int))
400 (defun find-a-pty ()
401 ;; First try to use the Unix98 pty api.
402 (let* ((master-name (coerce (format nil "/dev/ptmx") 'base-string))
403 (master-fd (sb-unix:unix-open master-name
404 sb-unix:o_rdwr
405 #o666)))
406 (when master-fd
407 (grantpt master-fd)
408 (unlockpt master-fd)
409 (let* ((slave-name (ptsname master-fd))
410 (slave-fd (sb-unix:unix-open slave-name
411 sb-unix:o_rdwr
412 #o666)))
413 (when slave-fd
414 (return-from find-a-pty
415 (values master-fd
416 slave-fd
417 slave-name)))
418 (sb-unix:unix-close master-fd))
419 (error "could not find a pty")))
420 ;; No dice, try using the old-school method.
421 (dolist (char '(#\p #\q))
422 (dotimes (digit 16)
423 (let* ((master-name (coerce (format nil "/dev/pty~C~X" char digit)
424 'base-string))
425 (master-fd (sb-unix:unix-open master-name
426 sb-unix:o_rdwr
427 #o666)))
428 (when master-fd
429 (let* ((slave-name (coerce (format nil "/dev/tty~C~X" char digit)
430 'base-string))
431 (slave-fd (sb-unix:unix-open slave-name
432 sb-unix:o_rdwr
433 #o666)))
434 (when slave-fd
435 (return-from find-a-pty
436 (values master-fd
437 slave-fd
438 slave-name)))
439 (sb-unix:unix-close master-fd))))))
440 (error "could not find a pty")))
442 #-win32
443 (defun open-pty (pty cookie)
444 (when pty
445 (multiple-value-bind
446 (master slave name)
447 (find-a-pty)
448 (push master *close-on-error*)
449 (push slave *close-in-parent*)
450 (when (streamp pty)
451 (multiple-value-bind (new-fd errno) (sb-unix:unix-dup master)
452 (unless new-fd
453 (error "couldn't SB-UNIX:UNIX-DUP ~W: ~A" master (strerror errno)))
454 (push new-fd *close-on-error*)
455 (copy-descriptor-to-stream new-fd pty cookie)))
456 (values name
457 (sb-sys:make-fd-stream master :input t :output t
458 :element-type :default
459 :dual-channel-p t)))))
461 (defmacro round-bytes-to-words (n)
462 (let ((bytes-per-word (/ sb-vm:n-machine-word-bits sb-vm:n-byte-bits)))
463 `(logandc2 (the fixnum (+ (the fixnum ,n)
464 (1- ,bytes-per-word))) (1- ,bytes-per-word))))
466 (defun string-list-to-c-strvec (string-list)
467 ;; Make a pass over STRING-LIST to calculate the amount of memory
468 ;; needed to hold the strvec.
469 (let ((string-bytes 0)
470 ;; We need an extra for the null, and an extra 'cause exect
471 ;; clobbers argv[-1].
472 (vec-bytes (* #.(/ sb-vm:n-machine-word-bits sb-vm:n-byte-bits)
473 (+ (length string-list) 2))))
474 (declare (fixnum string-bytes vec-bytes))
475 (dolist (s string-list)
476 (enforce-type s simple-string)
477 (incf string-bytes (round-bytes-to-words (1+ (length s)))))
478 ;; Now allocate the memory and fill it in.
479 (let* ((total-bytes (+ string-bytes vec-bytes))
480 (vec-sap (sb-sys:allocate-system-memory total-bytes))
481 (string-sap (sap+ vec-sap vec-bytes))
482 (i #.(/ sb-vm:n-machine-word-bits sb-vm:n-byte-bits)))
483 (declare (type (and unsigned-byte fixnum) total-bytes i)
484 (type sb-sys:system-area-pointer vec-sap string-sap))
485 (dolist (s string-list)
486 (declare (simple-string s))
487 (let ((n (length s)))
488 ;; Blast the string into place.
489 (sb-kernel:copy-ub8-to-system-area (the simple-base-string
490 ;; FIXME
491 (coerce s 'simple-base-string))
493 string-sap 0
494 (1+ n))
495 ;; Blast the pointer to the string into place.
496 (setf (sap-ref-sap vec-sap i) string-sap)
497 (setf string-sap (sap+ string-sap (round-bytes-to-words (1+ n))))
498 (incf i #.(/ sb-vm:n-machine-word-bits sb-vm:n-byte-bits))))
499 ;; Blast in the last null pointer.
500 (setf (sap-ref-sap vec-sap i) (int-sap 0))
501 (values vec-sap (sap+ vec-sap #.(/ sb-vm:n-machine-word-bits
502 sb-vm:n-byte-bits))
503 total-bytes))))
505 (defmacro with-c-strvec ((var str-list) &body body)
506 (with-unique-names (sap size)
507 `(multiple-value-bind
508 (,sap ,var ,size)
509 (string-list-to-c-strvec ,str-list)
510 (unwind-protect
511 (progn
512 ,@body)
513 (sb-sys:deallocate-system-memory ,sap ,size)))))
515 #-win32
516 (sb-alien:define-alien-routine spawn sb-alien:int
517 (program sb-alien:c-string)
518 (argv (* sb-alien:c-string))
519 (envp (* sb-alien:c-string))
520 (pty-name sb-alien:c-string)
521 (stdin sb-alien:int)
522 (stdout sb-alien:int)
523 (stderr sb-alien:int))
525 #+win32
526 (sb-alien:define-alien-routine spawn sb-win32::handle
527 (program sb-alien:c-string)
528 (argv (* sb-alien:c-string))
529 (stdin sb-alien:int)
530 (stdout sb-alien:int)
531 (stderr sb-alien:int)
532 (wait sb-alien:int))
534 ;;; Is UNIX-FILENAME the name of a file that we can execute?
535 (defun unix-filename-is-executable-p (unix-filename)
536 (let ((filename (coerce unix-filename 'string)))
537 (values (and (eq (sb-unix:unix-file-kind filename) :file)
538 #-win32
539 (sb-unix:unix-access filename sb-unix:x_ok)))))
541 (defun find-executable-in-search-path (pathname &optional
542 (search-path (posix-getenv "PATH")))
543 #+sb-doc
544 "Find the first executable file matching PATHNAME in any of the
545 colon-separated list of pathnames SEARCH-PATH"
546 (let ((program #-win32 pathname
547 #+win32 (merge-pathnames pathname (make-pathname :type "exe"))))
548 (loop for end = (position #-win32 #\: #+win32 #\; search-path
549 :start (if end (1+ end) 0))
550 and start = 0 then (and end (1+ end))
551 while start
552 ;; <Krystof> the truename of a file naming a directory is the
553 ;; directory, at least until pfdietz comes along and says why
554 ;; that's noncompliant -- CSR, c. 2003-08-10
555 for truename = (probe-file (subseq search-path start end))
556 for fullpath = (when truename
557 (unix-namestring (merge-pathnames program truename)))
558 when (and fullpath (unix-filename-is-executable-p fullpath))
559 return fullpath)))
561 ;;; FIXME: There shouldn't be two semiredundant versions of the
562 ;;; documentation. Since this is a public extension function, the
563 ;;; documentation should be in the doc string. So all information from
564 ;;; this comment should be merged into the doc string, and then this
565 ;;; comment can go away.
567 ;;; RUN-PROGRAM uses fork() and execve() to run a different program.
568 ;;; Strange stuff happens to keep the Unix state of the world
569 ;;; coherent.
571 ;;; The child process needs to get its input from somewhere, and send
572 ;;; its output (both standard and error) to somewhere. We have to do
573 ;;; different things depending on where these somewheres really are.
575 ;;; For input, there are five options:
576 ;;; -- T: Just leave fd 0 alone. Pretty simple.
577 ;;; -- "file": Read from the file. We need to open the file and
578 ;;; pull the descriptor out of the stream. The parent should close
579 ;;; this stream after the child is up and running to free any
580 ;;; storage used in the parent.
581 ;;; -- NIL: Same as "file", but use "/dev/null" as the file.
582 ;;; -- :STREAM: Use Unix pipe() to create two descriptors. Use
583 ;;; SB-SYS:MAKE-FD-STREAM to create the output stream on the
584 ;;; writeable descriptor, and pass the readable descriptor to
585 ;;; the child. The parent must close the readable descriptor for
586 ;;; EOF to be passed up correctly.
587 ;;; -- a stream: If it's a fd-stream, just pull the descriptor out
588 ;;; of it. Otherwise make a pipe as in :STREAM, and copy
589 ;;; everything across.
591 ;;; For output, there are five options:
592 ;;; -- T: Leave descriptor 1 alone.
593 ;;; -- "file": dump output to the file.
594 ;;; -- NIL: dump output to /dev/null.
595 ;;; -- :STREAM: return a stream that can be read from.
596 ;;; -- a stream: if it's a fd-stream, use the descriptor in it.
597 ;;; Otherwise, copy stuff from output to stream.
599 ;;; For error, there are all the same options as output plus:
600 ;;; -- :OUTPUT: redirect to the same place as output.
602 ;;; RUN-PROGRAM returns a PROCESS structure for the process if
603 ;;; the fork worked, and NIL if it did not.
605 #-win32
606 (defun run-program (program args
607 &key
608 (env nil env-p)
609 (environment (if env-p
610 (unix-environment-sbcl-from-cmucl env)
611 (posix-environ))
612 environment-p)
613 (wait t)
614 search
616 input
617 if-input-does-not-exist
618 output
619 (if-output-exists :error)
620 (error :output)
621 (if-error-exists :error)
622 status-hook)
623 #+sb-doc
624 "RUN-PROGRAM creates a new Unix process running the Unix program
625 found in the file specified by the PROGRAM argument. ARGS are the
626 standard arguments that can be passed to a Unix program. For no
627 arguments, use NIL (which means that just the name of the program is
628 passed as arg 0).
630 RUN-PROGRAM will return a PROCESS structure. See the CMU Common Lisp
631 Users Manual for details about the PROCESS structure.
633 Notes about Unix environments (as in the :ENVIRONMENT and :ENV args):
635 - The SBCL implementation of RUN-PROGRAM, like Perl and many other
636 programs, but unlike the original CMU CL implementation, copies
637 the Unix environment by default.
639 - Running Unix programs from a setuid process, or in any other
640 situation where the Unix environment is under the control of someone
641 else, is a mother lode of security problems. If you are contemplating
642 doing this, read about it first. (The Perl community has a lot of good
643 documentation about this and other security issues in script-like
644 programs.)
646 The &KEY arguments have the following meanings:
648 :ENVIRONMENT
649 a list of SIMPLE-BASE-STRINGs describing the new Unix environment
650 (as in \"man environ\"). The default is to copy the environment of
651 the current process.
652 :ENV
653 an alternative lossy representation of the new Unix environment,
654 for compatibility with CMU CL
655 :SEARCH
656 Look for PROGRAM in each of the directories along the $PATH
657 environment variable. Otherwise an absolute pathname is required.
658 (See also FIND-EXECUTABLE-IN-SEARCH-PATH)
659 :WAIT
660 If non-NIL (default), wait until the created process finishes. If
661 NIL, continue running Lisp until the program finishes.
662 :PTY
663 Either T, NIL, or a stream. Unless NIL, the subprocess is established
664 under a PTY. If :pty is a stream, all output to this pty is sent to
665 this stream, otherwise the PROCESS-PTY slot is filled in with a stream
666 connected to pty that can read output and write input.
667 :INPUT
668 Either T, NIL, a pathname, a stream, or :STREAM. If T, the standard
669 input for the current process is inherited. If NIL, /dev/null
670 is used. If a pathname, the file so specified is used. If a stream,
671 all the input is read from that stream and send to the subprocess. If
672 :STREAM, the PROCESS-INPUT slot is filled in with a stream that sends
673 its output to the process. Defaults to NIL.
674 :IF-INPUT-DOES-NOT-EXIST (when :INPUT is the name of a file)
675 can be one of:
676 :ERROR to generate an error
677 :CREATE to create an empty file
678 NIL (the default) to return NIL from RUN-PROGRAM
679 :OUTPUT
680 Either T, NIL, a pathname, a stream, or :STREAM. If T, the standard
681 output for the current process is inherited. If NIL, /dev/null
682 is used. If a pathname, the file so specified is used. If a stream,
683 all the output from the process is written to this stream. If
684 :STREAM, the PROCESS-OUTPUT slot is filled in with a stream that can
685 be read to get the output. Defaults to NIL.
686 :IF-OUTPUT-EXISTS (when :OUTPUT is the name of a file)
687 can be one of:
688 :ERROR (the default) to generate an error
689 :SUPERSEDE to supersede the file with output from the program
690 :APPEND to append output from the program to the file
691 NIL to return NIL from RUN-PROGRAM, without doing anything
692 :ERROR and :IF-ERROR-EXISTS
693 Same as :OUTPUT and :IF-OUTPUT-EXISTS, except that :ERROR can also be
694 specified as :OUTPUT in which case all error output is routed to the
695 same place as normal output.
696 :STATUS-HOOK
697 This is a function the system calls whenever the status of the
698 process changes. The function takes the process as an argument."
699 (when (and env-p environment-p)
700 (error "can't specify :ENV and :ENVIRONMENT simultaneously"))
701 ;; Make sure that the interrupt handler is installed.
702 (sb-sys:enable-interrupt sb-unix:sigchld #'sigchld-handler)
703 ;; Prepend the program to the argument list.
704 (push (namestring program) args)
705 (let (;; Clear various specials used by GET-DESCRIPTOR-FOR to
706 ;; communicate cleanup info.
707 *close-on-error*
708 *close-in-parent*
709 *handlers-installed*
710 ;; Establish PROC at this level so that we can return it.
711 proc
712 ;; It's friendly to allow the caller to pass any string
713 ;; designator, but internally we'd like SIMPLE-STRINGs.
714 (simple-args (mapcar (lambda (x) (coerce x 'simple-string)) args)))
715 (unwind-protect
716 (let ((pfile
717 (if search
718 (find-executable-in-search-path program)
719 (unix-namestring program)))
720 (cookie (list 0)))
721 (unless pfile
722 (error "no such program: ~S" program))
723 (unless (unix-filename-is-executable-p pfile)
724 (error "not executable: ~S" program))
725 (multiple-value-bind (stdin input-stream)
726 (get-descriptor-for input cookie
727 :direction :input
728 :if-does-not-exist if-input-does-not-exist)
729 (multiple-value-bind (stdout output-stream)
730 (get-descriptor-for output cookie
731 :direction :output
732 :if-exists if-output-exists)
733 (multiple-value-bind (stderr error-stream)
734 (if (eq error :output)
735 (values stdout output-stream)
736 (get-descriptor-for error cookie
737 :direction :output
738 :if-exists if-error-exists))
739 (multiple-value-bind (pty-name pty-stream)
740 (open-pty pty cookie)
741 ;; Make sure we are not notified about the child
742 ;; death before we have installed the PROCESS
743 ;; structure in *ACTIVE-PROCESSES*.
744 (with-active-processes-lock ()
745 (with-c-strvec (args-vec simple-args)
746 (with-c-strvec (environment-vec environment)
747 (let ((child-pid
748 (without-gcing
749 (spawn pfile args-vec environment-vec pty-name
750 stdin stdout stderr))))
751 (when (< child-pid 0)
752 (error "couldn't fork child process: ~A"
753 (strerror)))
754 (setf proc (make-process :pid child-pid
755 :%status :running
756 :pty pty-stream
757 :input input-stream
758 :output output-stream
759 :error error-stream
760 :status-hook status-hook
761 :cookie cookie))
762 (push proc *active-processes*))))))))))
763 (dolist (fd *close-in-parent*)
764 (sb-unix:unix-close fd))
765 (unless proc
766 (dolist (fd *close-on-error*)
767 (sb-unix:unix-close fd))
768 (dolist (handler *handlers-installed*)
769 (sb-sys:remove-fd-handler handler))))
770 (when (and wait proc)
771 (process-wait proc))
772 proc))
774 #+win32
775 (defun run-program (program args
776 &key
777 (wait t)
778 search
779 input
780 if-input-does-not-exist
781 output
782 (if-output-exists :error)
783 (error :output)
784 (if-error-exists :error)
785 status-hook)
786 "RUN-PROGRAM creates a new process specified by the PROGRAM
787 argument. ARGS are the standard arguments that can be passed to a
788 program. For no arguments, use NIL (which means that just the name of
789 the program is passed as arg 0).
791 RUN-PROGRAM will return a PROCESS structure. See the CMU
792 Common Lisp Users Manual for details about the PROCESS structure.
794 The &KEY arguments have the following meanings:
795 :SEARCH
796 Look for PROGRAM in each of the directories along the $PATH
797 environment variable. Otherwise an absolute pathname is required.
798 (See also FIND-EXECUTABLE-IN-SEARCH-PATH)
799 :WAIT
800 If non-NIL (default), wait until the created process finishes. If
801 NIL, continue running Lisp until the program finishes.
802 :INPUT
803 Either T, NIL, a pathname, a stream, or :STREAM. If T, the standard
804 input for the current process is inherited. If NIL, nul
805 is used. If a pathname, the file so specified is used. If a stream,
806 all the input is read from that stream and send to the subprocess. If
807 :STREAM, the PROCESS-INPUT slot is filled in with a stream that sends
808 its output to the process. Defaults to NIL.
809 :IF-INPUT-DOES-NOT-EXIST (when :INPUT is the name of a file)
810 can be one of:
811 :ERROR to generate an error
812 :CREATE to create an empty file
813 NIL (the default) to return NIL from RUN-PROGRAM
814 :OUTPUT
815 Either T, NIL, a pathname, a stream, or :STREAM. If T, the standard
816 output for the current process is inherited. If NIL, nul
817 is used. If a pathname, the file so specified is used. If a stream,
818 all the output from the process is written to this stream. If
819 :STREAM, the PROCESS-OUTPUT slot is filled in with a stream that can
820 be read to get the output. Defaults to NIL.
821 :IF-OUTPUT-EXISTS (when :OUTPUT is the name of a file)
822 can be one of:
823 :ERROR (the default) to generate an error
824 :SUPERSEDE to supersede the file with output from the program
825 :APPEND to append output from the program to the file
826 NIL to return NIL from RUN-PROGRAM, without doing anything
827 :ERROR and :IF-ERROR-EXISTS
828 Same as :OUTPUT and :IF-OUTPUT-EXISTS, except that :ERROR can also be
829 specified as :OUTPUT in which case all error output is routed to the
830 same place as normal output.
831 :STATUS-HOOK
832 This is a function the system calls whenever the status of the
833 process changes. The function takes the process as an argument."
834 ;; Prepend the program to the argument list.
835 (push (namestring program) args)
836 (let (;; Clear various specials used by GET-DESCRIPTOR-FOR to
837 ;; communicate cleanup info.
838 *close-on-error*
839 *close-in-parent*
840 ;; Establish PROC at this level so that we can return it.
841 proc
842 ;; It's friendly to allow the caller to pass any string
843 ;; designator, but internally we'd like SIMPLE-STRINGs.
844 (simple-args
845 (mapcar
846 (lambda (x)
847 (coerce
848 ;; Apparently any spaces or double quotes in the arguments
849 ;; need to be escaped on win32.
850 (if (position-if (lambda (c) (find c '(#\" #\Space))) x)
851 (write-to-string x)
853 'simple-string))
854 args)))
855 (unwind-protect
856 (let ((pfile
857 (if search
858 (find-executable-in-search-path program)
859 (unix-namestring program)))
860 (cookie (list 0)))
861 (unless pfile
862 (error "No such program: ~S" program))
863 (unless (unix-filename-is-executable-p pfile)
864 (error "Not an executable: ~S" program))
865 (multiple-value-bind (stdin input-stream)
866 (get-descriptor-for input cookie
867 :direction :input
868 :if-does-not-exist if-input-does-not-exist)
869 (multiple-value-bind (stdout output-stream)
870 (get-descriptor-for output cookie
871 :direction :output
872 :if-exists if-output-exists)
873 (multiple-value-bind (stderr error-stream)
874 (if (eq error :output)
875 (values stdout output-stream)
876 (get-descriptor-for error cookie
877 :direction :output
878 :if-exists if-error-exists))
879 (with-c-strvec (args-vec simple-args)
880 (let ((handle (without-gcing
881 (spawn pfile args-vec
882 stdin stdout stderr
883 (if wait 1 0)))))
884 (when (= handle -1)
885 (error "Couldn't spawn program: ~A" (strerror)))
886 (setf proc
887 (if wait
888 (make-process :pid handle
889 :%status :exited
890 :input input-stream
891 :output output-stream
892 :error error-stream
893 :status-hook status-hook
894 :cookie cookie
895 :exit-code handle)
896 (make-process :pid handle
897 :%status :running
898 :input input-stream
899 :output output-stream
900 :error error-stream
901 :status-hook status-hook
902 :cookie cookie)))
903 (push proc *active-processes*)))))))
904 (dolist (fd *close-in-parent*)
905 (sb-unix:unix-close fd)))
906 (unless proc
907 (dolist (fd *close-on-error*)
908 (sb-unix:unix-close fd)))
910 proc))
912 ;;; Install a handler for any input that shows up on the file
913 ;;; descriptor. The handler reads the data and writes it to the
914 ;;; stream.
915 (defun copy-descriptor-to-stream (descriptor stream cookie)
916 (incf (car cookie))
917 (let ((string (make-string 256 :element-type 'base-char))
918 handler)
919 (setf handler
920 (sb-sys:add-fd-handler
921 descriptor
922 :input (lambda (fd)
923 (declare (ignore fd))
924 (loop
925 (unless handler
926 (return))
927 (multiple-value-bind
928 (result readable/errno)
929 (sb-unix:unix-select (1+ descriptor)
930 (ash 1 descriptor)
931 0 0 0)
932 (cond ((null result)
933 (error "~@<couldn't select on sub-process: ~
934 ~2I~_~A~:>"
935 (strerror readable/errno)))
936 ((zerop result)
937 (return))))
938 (sb-alien:with-alien ((buf (sb-alien:array
939 sb-alien:char
940 256)))
941 (multiple-value-bind
942 (count errno)
943 (sb-unix:unix-read descriptor
944 (alien-sap buf)
945 256)
946 (cond (#-win32(or (and (null count)
947 (eql errno sb-unix:eio))
948 (eql count 0))
949 #+win32(<= count 0)
950 (sb-sys:remove-fd-handler handler)
951 (setf handler nil)
952 (decf (car cookie))
953 (sb-unix:unix-close descriptor)
954 (return))
955 ((null count)
956 (sb-sys:remove-fd-handler handler)
957 (setf handler nil)
958 (decf (car cookie))
959 (error
960 "~@<couldn't read input from sub-process: ~
961 ~2I~_~A~:>"
962 (strerror errno)))
964 (sb-kernel:copy-ub8-from-system-area
965 (alien-sap buf) 0
966 string 0
967 count)
968 (write-string string stream
969 :end count)))))))))))
971 (defun get-stream-fd (stream direction)
972 (typecase stream
973 (sb-sys:fd-stream
974 (values (sb-sys:fd-stream-fd stream) nil))
975 (synonym-stream
976 (get-stream-fd (symbol-value (synonym-stream-symbol stream)) direction))
977 (two-way-stream
978 (ecase direction
979 (:input
980 (get-stream-fd (two-way-stream-input-stream stream) direction))
981 (:output
982 (get-stream-fd (two-way-stream-output-stream stream) direction))))))
984 ;;; Find a file descriptor to use for object given the direction.
985 ;;; Returns the descriptor. If object is :STREAM, returns the created
986 ;;; stream as the second value.
987 (defun get-descriptor-for (object
988 cookie
989 &rest keys
990 &key direction
991 &allow-other-keys)
992 (cond ((eq object t)
993 ;; No new descriptor is needed.
994 (values -1 nil))
995 ((eq object nil)
996 ;; Use /dev/null.
997 (multiple-value-bind
998 (fd errno)
999 (sb-unix:unix-open #-win32 #.(coerce "/dev/null" 'base-string)
1000 #+win32 #.(coerce "nul" 'base-string)
1001 (case direction
1002 (:input sb-unix:o_rdonly)
1003 (:output sb-unix:o_wronly)
1004 (t sb-unix:o_rdwr))
1005 #o666)
1006 (unless fd
1007 (error #-win32 "~@<couldn't open \"/dev/null\": ~2I~_~A~:>"
1008 #+win32 "~@<couldn't open \"nul\" device: ~2I~_~A~:>"
1009 (strerror errno)))
1010 (push fd *close-in-parent*)
1011 (values fd nil)))
1012 ((eq object :stream)
1013 (multiple-value-bind (read-fd write-fd) (sb-unix:unix-pipe)
1014 (unless read-fd
1015 (error "couldn't create pipe: ~A" (strerror write-fd)))
1016 (case direction
1017 (:input
1018 (push read-fd *close-in-parent*)
1019 (push write-fd *close-on-error*)
1020 (let ((stream (sb-sys:make-fd-stream write-fd :output t
1021 :element-type :default)))
1022 (values read-fd stream)))
1023 (:output
1024 (push read-fd *close-on-error*)
1025 (push write-fd *close-in-parent*)
1026 (let ((stream (sb-sys:make-fd-stream read-fd :input t
1027 :element-type :default)))
1028 (values write-fd stream)))
1030 (sb-unix:unix-close read-fd)
1031 (sb-unix:unix-close write-fd)
1032 (error "Direction must be either :INPUT or :OUTPUT, not ~S."
1033 direction)))))
1034 ((or (pathnamep object) (stringp object))
1035 (with-open-stream (file (apply #'open object keys))
1036 (multiple-value-bind
1037 (fd errno)
1038 (sb-unix:unix-dup (sb-sys:fd-stream-fd file))
1039 (cond (fd
1040 (push fd *close-in-parent*)
1041 (values fd nil))
1043 (error "couldn't duplicate file descriptor: ~A"
1044 (strerror errno)))))))
1045 ((streamp object)
1046 (ecase direction
1047 (:input
1048 (or (get-stream-fd object :input)
1049 ;; FIXME: We could use a better way of setting up
1050 ;; temporary files
1051 (dotimes (count
1053 (error "could not open a temporary file in /tmp"))
1054 (let* ((name (coerce (format nil "/tmp/.run-program-~D" count)
1055 'base-string))
1056 (fd (sb-unix:unix-open name
1057 (logior sb-unix:o_rdwr
1058 sb-unix:o_creat
1059 sb-unix:o_excl)
1060 #o666)))
1061 (sb-unix:unix-unlink name)
1062 (when fd
1063 (let ((newline (string #\Newline)))
1064 (loop
1065 (multiple-value-bind
1066 (line no-cr)
1067 (read-line object nil nil)
1068 (unless line
1069 (return))
1070 (sb-unix:unix-write
1072 ;; FIXME: this really should be
1073 ;; (STRING-TO-OCTETS :EXTERNAL-FORMAT ...).
1074 ;; RUN-PROGRAM should take an
1075 ;; external-format argument, which should
1076 ;; be passed down to here. Something
1077 ;; similar should happen on :OUTPUT, too.
1078 (map '(vector (unsigned-byte 8)) #'char-code line)
1079 0 (length line))
1080 (if no-cr
1081 (return)
1082 (sb-unix:unix-write fd newline 0 1)))))
1083 (sb-unix:unix-lseek fd 0 sb-unix:l_set)
1084 (push fd *close-in-parent*)
1085 (return (values fd nil)))))))
1086 (:output
1087 (or (get-stream-fd object :output)
1088 (multiple-value-bind (read-fd write-fd)
1089 (sb-unix:unix-pipe)
1090 (unless read-fd
1091 (error "couldn't create pipe: ~S" (strerror write-fd)))
1092 (copy-descriptor-to-stream read-fd object cookie)
1093 (push read-fd *close-on-error*)
1094 (push write-fd *close-in-parent*)
1095 (values write-fd nil))))))
1097 (error "invalid option to RUN-PROGRAM: ~S" object))))