1 /* Copyright (C) 1995, 1996, 1999 Aladdin Enterprises. All rights reserved. 2 3 This software is provided AS-IS with no warranty, either express or 4 implied. 5 6 This software is distributed under license and may not be copied, 7 modified or distributed except as expressly authorized under the terms 8 of the license contained in the file LICENSE in this distribution. 9 10 For more information about licensing, please refer to 11 http://www.ghostscript.com/licensing/. For information on 12 commercial licensing, go to http://www.artifex.com/licensing/ or 13 contact Artifex Software, Inc., 101 Lucas Valley Road #110, 14 San Rafael, CA 94903, U.S.A., +1(415)492-9861. 15 */ 16 17 /* $Id: imain.h,v 1.9 2004/08/04 23:33:29 stefan Exp $ */ 18 /* Interface to imain.c */ 19 /* Requires <stdio.h>, stdpre.h, gsmemory.h, gstypes.h, iref.h */ 20 21 #ifndef imain_INCLUDED 22 # define imain_INCLUDED 23 24 #include "gsexit.h" /* exported by imain.c */ 25 26 /* 27 * This file defines the intended API between client front ends 28 * (such as imainarg.c, the command-line-driven front end) 29 * and imain.c, which provides top-level control of the interpreter. 30 */ 31 32 /* ================ Types ================ */ 33 34 /* 35 * Currently, the interpreter has a lot of static variables, but 36 * eventually it will have none, so that clients will be able to make 37 * multiple instances of it. In anticipation of this, many of the 38 * top-level API calls take an interpreter instance (gs_main_instance *) 39 * as their first argument. 40 */ 41 #ifndef gs_main_instance_DEFINED 42 # define gs_main_instance_DEFINED 43 typedef struct gs_main_instance_s gs_main_instance; 44 #endif 45 46 /* ================ Exported procedures from imain.c ================ */ 47 48 /* get minst from memory is a hack to allow parts of the system 49 * to reach minst, slightly better than a global 50 */ 51 gs_main_instance* get_minst_from_memory(const gs_memory_t *mem); 52 53 /* ---------------- Instance creation ---------------- */ 54 55 /* 56 * NB: multiple instances are not supported yet 57 * 58 * // add usage documentation 59 */ 60 gs_main_instance *gs_main_alloc_instance(gs_memory_t *); 61 62 /* ---------------- Initialization ---------------- */ 63 64 /* 65 * The interpreter requires three initialization steps, called init0, 66 * init1, and init2. These steps must be done in that order, but 67 * init1 may be omitted. 68 */ 69 70 /* 71 * init0 records the files to be used for stdio, and initializes the 72 * graphics library, the file search paths, and other instance data. 73 */ 74 int gs_main_init0(gs_main_instance *minst, FILE *in, FILE *out, FILE *err, 75 int max_lib_paths); 76 77 /* 78 * init1 initializes the memory manager and other internal data 79 * structures such as the name table, the token scanner tables, 80 * dictionaries such as systemdict, and the interpreter stacks. 81 */ 82 int gs_main_init1(gs_main_instance * minst); 83 84 /* 85 * init2 finishes preparing the interpreter for use by running 86 * initialization files with PostScript procedure definitions. 87 */ 88 int gs_main_init2(gs_main_instance * minst); 89 90 /* 91 * The runlibfile operator uses a search path, as described in 92 * Use.htm, for looking up file names. Each interpreter instance has 93 * its own search path. The following call adds a directory or set of 94 * directories to the search path; it is equivalent to the -I command 95 * line switch. It may be called any time after init0. 96 */ 97 int gs_main_add_lib_path(gs_main_instance * minst, const char *path); 98 99 /* 100 * Under certain internal conditions, the search path may temporarily 101 * be in an inconsistent state; gs_main_set_lib_paths takes care of 102 * this. Clients should never need to call this procedure, and 103 * eventually it may be removed. 104 */ 105 int gs_main_set_lib_paths(gs_main_instance * minst); 106 107 /* 108 * Open a PostScript file using the search path. Clients should 109 * never need to call this procedure, since gs_main_run_file opens the 110 * file itself, and eventually the procedure may be removed. 111 */ 112 int gs_main_lib_open(gs_main_instance * minst, const char *fname, 113 ref * pfile); 114 115 /* 116 * Here we summarize the C API calls that correspond to some of the 117 * most common command line switches documented in Use.htm, to help 118 * clients who are familiar with the command line and are starting to 119 * use the API. 120 * 121 * -d/D, -s/S (for setting device parameters like OutputFile) 122 * Use the C API for device parameters documented near the 123 * end of gsparam.h. 124 * 125 * -d/D (for setting Boolean parameters like NOPAUSE) 126 * { ref vtrue; 127 * make_true(&vtrue); 128 * dict_put_string(systemdict, "NOPAUSE", &vtrue); 129 * } 130 * -I 131 * Use gs_main_add_lib_path, documented above. 132 * 133 * -A, -A- 134 * Set gs_debug['@'] = 1 or 0 respectively. 135 * -E, -E- 136 * Set gs_debug['#'] = 1 or 0 respectively. 137 * -Z..., -Z-... 138 * Set gs_debug[c] = 1 or 0 respectively for each character 139 * c in the string. 140 */ 141 142 /* ---------------- Execution ---------------- */ 143 144 /* 145 * After initializing the interpreter, clients may pass it files or 146 * strings to be interpreted. There are four ways to do this: 147 * - Pass a file name (gs_main_run_file); 148 * - Pass a C string (gs_main_run_string); 149 * - Pass a string defined by pointer and length 150 * (gs_main_run_string_with_length); 151 * - Pass strings piece-by-piece 152 * (gs_main_run_string_begin/continue/end). 153 * 154 * The value returned by the first three of these calls is 155 * 0 if the interpreter ran to completion, e_Quit for a normal quit, 156 * or e_Fatal for a non-zero quit or a fatal error. 157 * e_Fatal stores the exit code in the third argument. 158 * The str argument of gs_main_run_string[_with_length] must be allocated 159 * in non-garbage-collectable space (e.g., by malloc or gs_malloc, 160 * or statically). 161 */ 162 int gs_main_run_file(gs_main_instance * minst, const char *fname, 163 int user_errors, int *pexit_code, 164 ref * perror_object); 165 int gs_main_run_string(gs_main_instance * minst, const char *str, 166 int user_errors, int *pexit_code, 167 ref * perror_object); 168 int gs_main_run_string_with_length(gs_main_instance * minst, 169 const char *str, uint length, 170 int user_errors, int *pexit_code, 171 ref * perror_object); 172 173 /* 174 * Open the file for gs_main_run_file. This is an internal routine 175 * that is only exported for some special clients. 176 */ 177 int gs_main_run_file_open(gs_main_instance * minst, 178 const char *file_name, ref * pfref); 179 180 /* 181 * The next 3 procedures provide for feeding input to the interpreter 182 * in arbitrary chunks, unlike run_string, which requires that each string 183 * be a properly formed PostScript program fragment. To use them: 184 * Call run_string_begin. 185 * Call run_string_continue as many times as desired, 186 * stopping if it returns anything other than e_NeedInput. 187 * If run_string_continue didn't indicate an error or a quit 188 * (i.e., a return value other than e_NeedInput), call run_string_end 189 * to provide an EOF indication. 190 * Note that run_string_continue takes a pointer and a length, like 191 * run_string_with_length. 192 */ 193 int gs_main_run_string_begin(gs_main_instance * minst, int user_errors, 194 int *pexit_code, ref * perror_object); 195 int gs_main_run_string_continue(gs_main_instance * minst, 196 const char *str, uint length, 197 int user_errors, int *pexit_code, 198 ref * perror_object); 199 int gs_main_run_string_end(gs_main_instance * minst, int user_errors, 200 int *pexit_code, ref * perror_object); 201 202 /* ---------------- Operand stack access ---------------- */ 203 204 /* 205 * The following procedures are not used in normal operation; 206 * they exist only to allow clients driving the interpreter through the 207 * gs_main_run_xxx procedures to push parameters quickly and to get results 208 * back. The push procedures return 0, e_stackoverflow, or e_VMerror; 209 * the pop procedures return 0, e_stackunderflow, or e_typecheck. 210 * 211 * Procedures to push values on the operand stack: 212 */ 213 int gs_push_boolean(gs_main_instance * minst, bool value); 214 int gs_push_integer(gs_main_instance * minst, long value); 215 int gs_push_real(gs_main_instance * minst, floatp value); 216 int gs_push_string(gs_main_instance * minst, byte * chars, uint length, 217 bool read_only); 218 219 /* 220 * Procedures to pop values from the operand stack: 221 */ 222 int gs_pop_boolean(gs_main_instance * minst, bool * result); 223 int gs_pop_integer(gs_main_instance * minst, long *result); 224 int gs_pop_real(gs_main_instance * minst, float *result); 225 226 /* gs_pop_string returns 1 if the string is read-only. */ 227 int gs_pop_string(gs_main_instance * minst, gs_string * result); 228 229 /* ---------------- Debugging ---------------- */ 230 231 /* 232 * Print an error mesage including the error code, error object (if any), 233 * and operand and execution stacks in hex. Clients will probably 234 * never call this. 235 */ 236 void gs_main_dump_stack(gs_main_instance *minst, int code, 237 ref * perror_object); 238 239 /* ---------------- Console output ---------------- */ 240 241 242 243 244 /* ---------------- Termination ---------------- */ 245 246 /* 247 * Terminate the interpreter by closing all devices and releasing all 248 * allocated memory. Currently, because of some technical problems 249 * with statically initialized data, it is not possible to reinitialize 250 * the interpreter after terminating it; we plan to fix this as soon as 251 * possible. 252 * 253 * Note that calling gs_to_exit (defined in gsexit.h) automatically calls 254 * gs_main_finit for the default instance. 255 */ 256 int gs_main_finit(gs_main_instance * minst, int exit_status, int code); 257 258 #endif /* imain_INCLUDED */ 259