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

Last change on this file since 13361 was 13361, checked in by Mark Evenson, 10 years ago

Edit RUN-PROGRAM documentation lightly.

File size: 6.1 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;;; Vaguely inspired by sb-ext:run-program in SBCL.
37;;;
38;;; See <http://www.sbcl.org/manual/Running-external-programs.html>.
39;;;
40;;; This implementation uses the JVM facilities for running external
41;;; processes.
42;;; <http://download.oracle.com/javase/6/docs/api/java/lang/ProcessBuilder.html>.
43(defun run-program (program args &key environment (wait t))
44  ;;For documentation, see below.
45  (let ((pb (%make-process-builder program args)))
46    (when environment
47      (let ((env-map (%process-builder-environment pb)))
48        (dolist (entry environment)
49          (%process-builder-env-put env-map
50                                    (princ-to-string (car entry))
51                                    (princ-to-string (cdr entry))))))
52    (let ((process (make-process (%process-builder-start pb))))
53      (when wait (process-wait process))
54      process)))
55
56(setf (documentation 'run-program 'function)
57      "Creates a new process running the the PROGRAM.
58ARGS are a list of strings to be passed to the program as arguments.
59
60For no arguments, use nil which means that just the name of the
61program is passed as arg 0.
62
63Returns a process structure containing the JAVA-OBJECT wrapped Process
64object, and the PROCESS-INPUT, PROCESS-OUTPUT, and PROCESS-ERROR streams.
65
66c.f. http://download.oracle.com/javase/6/docs/api/java/lang/Process.html
67
68Notes about Unix environments (as in the :environment):
69
70    * The ABCL implementation of run-program, like SBCL, Perl and many
71      other programs, copies the Unix environment by default.
72
73    * Running Unix programs from a setuid process, or in any other
74      situation where the Unix environment is under the control of
75      someone else, is a mother lode of security problems. If you are
76      contemplating doing this, read about it first. (The Perl
77      community has a lot of good documentation about this and other
78      security issues in script-like programs.)
79
80The &key arguments have the following meanings:
81
82:environment
83    An alist of STRINGs (name . value) describing the new
84    environment. The default is to copy the environment of the current
85    process.
86
87:wait
88    If non-NIL, which is the default, wait until the created process
89    finishes. If NIL, continue running Lisp until the program
90    finishes.")
91
92;;The process structure.
93
94(defstruct (process (:constructor %make-process (jprocess)))
95  jprocess input output error)
96
97(defun make-process (proc)
98  (let ((process (%make-process proc)))
99    (setf (process-input process) (%make-process-input-stream proc))
100    (setf (process-output process) (%make-process-output-stream proc))
101    (setf (process-error process) (%make-process-error-stream proc))
102    process))
103
104(defun process-alive-p (process)
105  "Return t if process is still alive, nil otherwise."
106  (%process-alive-p (process-jprocess process)))
107
108(defun process-wait (process)
109  "Wait for process to quit running for some reason."
110  (%process-wait (process-jprocess process)))
111
112(defun process-exit-code (instance)
113  "The exit code of a process."
114  (%process-exit-code (process-jprocess instance)))
115
116(defun process-kill (process)
117  "Kills the process."
118  (%process-kill (process-jprocess process)))
119
120;;; Low-level functions. For now they're just a refactoring of the
121;;; initial implementation with direct jnew & jcall forms in the
122;;; code. As per Ville's suggestion, these should really be implemented
123;;; as primitives.
124(defun %make-process-builder (program args)
125  (java:jnew "java.lang.ProcessBuilder"
126             (java:jnew-array-from-list "java.lang.String" (cons program args))))
127
128(defun %process-builder-environment (pb)
129  (java:jcall "environment" pb))
130
131(defun %process-builder-env-put (env-map key value)
132  (java:jcall "put" env-map key value))
133
134(defun %process-builder-start (pb)
135  (java:jcall "start" pb))
136
137(defun %make-process-input-stream (proc)
138  (java:jnew "org.armedbear.lisp.Stream" 'system-stream
139             (java:jcall "getOutputStream" proc) ;;not a typo!
140             'character))
141
142(defun %make-process-output-stream (proc)
143  (java:jnew "org.armedbear.lisp.Stream" 'system-stream
144             (java:jcall "getInputStream" proc) ;;not a typo|
145             'character))
146
147(defun %make-process-error-stream (proc)
148  (java:jnew "org.armedbear.lisp.Stream" 'system-stream
149             (java:jcall "getErrorStream" proc)
150             'character))
151
152(defun %process-alive-p (jprocess)
153  (not (ignore-errors (java:jcall "exitValue" jprocess))))
154
155(defun %process-wait (jprocess)
156  (java:jcall "waitFor" jprocess))
157
158(defun %process-exit-code (jprocess)
159  (ignore-errors (java:jcall "exitValue" jprocess)))
160
161(defun %process-kill (jprocess)
162  (java:jcall "destroy" jprocess))
Note: See TracBrowser for help on using the repository browser.