source: trunk/abcl/src/org/armedbear/lisp/run-program.lisp @ 14235

Last change on this file since 14235 was 14235, checked in by Mark Evenson, 8 years ago

RUN-PROGRAM: refactor symbols and improve docstring.

File size: 6.8 KB
Line 
1;;; run-program.lisp
2;;;
3;;; Copyright (C) 2011 Alessio Stalla
4;;; $Id$
5;;;
6;;; This program is free software; you can redistribute it and/or
7;;; modify it under the terms of the GNU General Public License
8;;; as published by the Free Software Foundation; either version 2
9;;; of the License, or (at your option) any later version.
10;;;
11;;; This program is distributed in the hope that it will be useful,
12;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
13;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14;;; GNU General Public License for more details.
15;;;
16;;; You should have received a copy of the GNU General Public License
17;;; along with this program; if not, write to the Free Software
18;;; Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
19;;;
20;;; As a special exception, the copyright holders of this library give you
21;;; permission to link this library with independent modules to produce an
22;;; executable, regardless of the license terms of these independent
23;;; modules, and to copy and distribute the resulting executable under
24;;; terms of your choice, provided that you also meet, for each linked
25;;; independent module, the terms and conditions of the license of that
26;;; module.  An independent module is a module which is not derived from
27;;; or based on this library.  If you modify this library, you may extend
28;;; this exception to your version of the library, but you are not
29;;; obligated to do so.  If you do not wish to do so, delete this
30;;; exception statement from your version.
31
32(in-package "SYSTEM")
33
34(require "JAVA")
35
36(export '(run-program process process-p process-input process-output
37          process-error process-alive-p process-wait process-exit-code
38          process-kill))
39
40;;; Vaguely inspired by sb-ext:run-program in SBCL.
41;;;
42;;; See <http://www.sbcl.org/manual/Running-external-programs.html>.
43;;;
44;;; This implementation uses the JVM facilities for running external
45;;; processes.
46;;; <http://download.oracle.com/javase/6/docs/api/java/lang/ProcessBuilder.html>.
47(defun run-program (program args &key environment (wait t) clear-environment)
48  "Run PROGRAM with ARGS in with ENVIRONMENT variables.
49Possibly WAIT for subprocess to exit.
50
51Optionally CLEAR-ENVIRONMENT of the subprocess of any non specified values."
52  ;;For documentation, see below.
53  (let* ((program-namestring (namestring (pathname program)))
54
55         (process-builder (%make-process-builder program-namestring args)))
56    (let ((env-map (%process-builder-environment process-builder)))
57      (when clear-environment
58        (%process-builder-env-clear env-map))           
59      (when environment
60        (dolist (entry environment)
61          (%process-builder-env-put env-map
62                                    (princ-to-string (car entry))
63                                    (princ-to-string (cdr entry))))))
64    (let ((process (make-process (%process-builder-start process-builder))))
65      (when wait (process-wait process))
66      process)))
67
68(setf (documentation 'run-program 'function)
69      "Creates a new process running the the PROGRAM.
70ARGS are a list of strings to be passed to the program as arguments.
71
72For no arguments, use nil which means that just the name of the
73program is passed as arg 0.
74
75Returns a process structure containing the JAVA-OBJECT wrapped Process
76object, and the PROCESS-INPUT, PROCESS-OUTPUT, and PROCESS-ERROR streams.
77
78c.f. http://download.oracle.com/javase/6/docs/api/java/lang/Process.html
79
80Notes about Unix environments (as in the :environment):
81
82    * The ABCL implementation of run-program, like SBCL, Perl and many
83      other programs, copies the Unix environment by default.
84
85    * Running Unix programs from a setuid process, or in any other
86      situation where the Unix environment is under the control of
87      someone else, is a mother lode of security problems. If you are
88      contemplating doing this, read about it first. (The Perl
89      community has a lot of good documentation about this and other
90      security issues in script-like programs.)
91
92The &key arguments have the following meanings:
93
94:environment
95    An alist of STRINGs (name . value) describing new
96    environment values that replace existing ones.
97
98:clear-env
99    If non-NIL, the current environment is cleared before the
100    values supplied by :environment are inserted.
101
102:wait
103    If non-NIL, which is the default, wait until the created process
104    finishes. If NIL, continue running Lisp until the program
105    finishes.")
106
107;;The process structure.
108
109(defstruct (process (:constructor %make-process (jprocess)))
110  jprocess input output error)
111
112(defun make-process (proc)
113  (let ((process (%make-process proc)))
114    (setf (process-input process) (%make-process-input-stream proc))
115    (setf (process-output process) (%make-process-output-stream proc))
116    (setf (process-error process) (%make-process-error-stream proc))
117    process))
118
119(defun process-alive-p (process)
120  "Return t if process is still alive, nil otherwise."
121  (%process-alive-p (process-jprocess process)))
122
123(defun process-wait (process)
124  "Wait for process to quit running for some reason."
125  (%process-wait (process-jprocess process)))
126
127(defun process-exit-code (instance)
128  "The exit code of a process."
129  (%process-exit-code (process-jprocess instance)))
130
131(defun process-kill (process)
132  "Kills the process."
133  (%process-kill (process-jprocess process)))
134
135;;; Low-level functions. For now they're just a refactoring of the
136;;; initial implementation with direct jnew & jcall forms in the
137;;; code. As per Ville's suggestion, these should really be implemented
138;;; as primitives.
139(defun %make-process-builder (program args)
140  (java:jnew "java.lang.ProcessBuilder"
141             (java:jnew-array-from-list "java.lang.String" (cons program args))))
142
143(defun %process-builder-environment (pb)
144  (java:jcall "environment" pb))
145
146(defun %process-builder-env-put (env-map key value)
147  (java:jcall "put" env-map key value))
148
149(defun %process-builder-env-clear (env-map)
150  (java:jcall "clear" env-map))
151
152(defun %process-builder-start (pb)
153  (java:jcall "start" pb))
154
155(defun %make-process-input-stream (proc)
156  (java:jnew "org.armedbear.lisp.Stream" 'system-stream
157             (java:jcall "getOutputStream" proc) ;;not a typo!
158             'character))
159
160(defun %make-process-output-stream (proc)
161  (java:jnew "org.armedbear.lisp.Stream" 'system-stream
162             (java:jcall "getInputStream" proc) ;;not a typo|
163             'character))
164
165(defun %make-process-error-stream (proc)
166  (java:jnew "org.armedbear.lisp.Stream" 'system-stream
167             (java:jcall "getErrorStream" proc)
168             'character))
169
170(defun %process-alive-p (jprocess)
171  (not (ignore-errors (java:jcall "exitValue" jprocess))))
172
173(defun %process-wait (jprocess)
174  (java:jcall "waitFor" jprocess))
175
176(defun %process-exit-code (jprocess)
177  (ignore-errors (java:jcall "exitValue" jprocess)))
178
179(defun %process-kill (jprocess)
180  (java:jcall "destroy" jprocess))
Note: See TracBrowser for help on using the repository browser.