1 /* Copyright (C) 1991-2004 artofcode LLC. 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: gp.h,v 1.27 2004/01/15 09:27:10 giles Exp $ */ 18 /* Interface to platform-specific routines */ 19 /* Requires gsmemory.h */ 20 21 #ifndef gp_INCLUDED 22 # define gp_INCLUDED 23 24 #include "gstypes.h" 25 /* 26 * This file defines the interface to ***ALL*** platform-specific routines, 27 * with the exception of the thread/synchronization interface (gpsync.h) 28 * and getenv (gpgetenv.h). The implementations are in gp_*.c files 29 * specific to each platform. We try very hard to keep this list short! 30 */ 31 /* 32 * gp_getenv is declared in a separate file because a few places need it 33 * and don't want to include any of the other gs definitions. 34 */ 35 #include "gpgetenv.h" 36 /* 37 * The prototype for gp_readline is in srdline.h, since it is shared with 38 * stream.h. 39 */ 40 #include "srdline.h" 41 42 /* ------ Initialization/termination ------ */ 43 44 /* 45 * This routine is called early in the initialization. 46 * It should do as little as possible. In particular, it should not 47 * do things like open display connections: that is the responsibility 48 * of the display device driver. 49 */ 50 void gp_init(void); 51 52 /* 53 * This routine is called just before the program exits (normally or 54 * abnormally). It too should do as little as possible. 55 */ 56 void gp_exit(int exit_status, int code); 57 58 /* 59 * Exit the program. Normally this just calls the `exit' library procedure, 60 * but it does something different on a few platforms. 61 */ 62 void gp_do_exit(int exit_status); 63 64 /* ------ Miscellaneous ------ */ 65 66 /* 67 * Get the string corresponding to an OS error number. 68 * If no string is available, return NULL. The caller may assume 69 * the string is allocated statically and permanently. 70 */ 71 const char *gp_strerror(int); 72 73 /* ------ Date and time ------ */ 74 75 /* 76 * Read the current time (in seconds since an implementation-defined epoch) 77 * into ptm[0], and fraction (in nanoseconds) into ptm[1]. 78 */ 79 void gp_get_realtime(long ptm[2]); 80 81 /* 82 * Read the current user CPU time (in seconds) into ptm[0], 83 * and fraction (in nanoseconds) into ptm[1]. 84 */ 85 void gp_get_usertime(long ptm[2]); 86 87 /* ------ Reading lines from stdin ------ */ 88 89 /* 90 * These routines are intended to provide an abstract interface to GNU 91 * readline or to other packages that offer enhanced line-reading 92 * capability. 93 */ 94 95 /* 96 * Allocate a state structure for line reading. This is called once at 97 * initialization. *preadline_data is an opaque pointer that is passed 98 * back to gp_readline and gp_readline_finit. 99 */ 100 int gp_readline_init(void **preadline_data, gs_memory_t *mem); 101 102 /* 103 * See srdline.h for the definition of sreadline_proc. 104 */ 105 int gp_readline(stream *s_in, stream *s_out, void *readline_data, 106 gs_const_string *prompt, gs_string *buf, 107 gs_memory_t *bufmem, uint *pcount, bool *pin_eol, 108 bool (*is_stdin)(const stream *)); 109 110 /* 111 * Free a readline state. 112 */ 113 void gp_readline_finit(void *readline_data); 114 115 /* ------ Reading from stdin, unbuffered if possible ------ */ 116 117 /* Read bytes from stdin, using unbuffered if possible. 118 * Store up to len bytes in buf. 119 * Returns number of bytes read, or 0 if EOF, or -ve if error. 120 * If unbuffered is NOT possible, fetch 1 byte if interactive 121 * is non-zero, or up to len bytes otherwise. 122 * If unbuffered is possible, fetch at least 1 byte (unless error or EOF) 123 * and any additional bytes that are available without blocking. 124 */ 125 int gp_stdin_read(char *buf, int len, int interactive, FILE *f); 126 127 /* ------ Screen management ------ */ 128 129 /* 130 * The following are only relevant for X Windows. 131 */ 132 133 /* Get the environment variable that specifies the display to use. */ 134 const char *gp_getenv_display(void); 135 136 /* ------ File naming and accessing ------ */ 137 138 /* 139 * Define the maximum size of a file name returned by gp_open_scratch_file 140 * or gp_open_printer. (This should really be passed as an additional 141 * parameter, but it would break too many clients to make this change now.) 142 * Note that this is the size of the buffer, not the maximum number of 143 * characters: the latter is one less, because of the terminating \0. 144 */ 145 #define gp_file_name_sizeof 260 /* == MAX_PATH on Windows */ 146 147 /* Define the character used for separating file names in a list. */ 148 extern const char gp_file_name_list_separator; 149 150 /* Define the default scratch file name prefix. */ 151 extern const char gp_scratch_file_name_prefix[]; 152 153 /* Define the name of the null output file. */ 154 extern const char gp_null_file_name[]; 155 156 /* Define the name that designates the current directory. */ 157 extern const char gp_current_directory_name[]; 158 159 /* Define the string to be concatenated with the file mode */ 160 /* for opening files without end-of-line conversion. */ 161 /* This is always either "" or "b". */ 162 extern const char gp_fmode_binary_suffix[]; 163 164 /* Define the file modes for binary reading or writing. */ 165 /* (This is just a convenience: they are "r" or "w" + the suffix.) */ 166 extern const char gp_fmode_rb[]; 167 extern const char gp_fmode_wb[]; 168 169 /** 170 * gp_open_scratch_file: Create a scratch file. 171 * @prefix: Name prefix. 172 * @fname: Where to store filename of newly created file. 173 * @mode: File access mode (in fopen syntax). 174 * 175 * Creates a scratch (temporary) file in the filesystem. The exact 176 * location and name of the file is platform dependent, but in general 177 * uses @prefix as a prefix. If @prefix is not absolute, then choose 178 * an appropriate system directory, usually as determined from 179 * gp_gettmpdir(), followed by a path as returned from a system call. 180 * 181 * Implementations should make sure that 182 * 183 * Return value: Opened file object, or NULL on error. 184 **/ 185 FILE *gp_open_scratch_file(const char *prefix, 186 char fname[gp_file_name_sizeof], 187 const char *mode); 188 189 /* Open a file with the given name, as a stream of uninterpreted bytes. */ 190 FILE *gp_fopen(const char *fname, const char *mode); 191 192 /* Force given file into binary mode (no eol translations, etc) */ 193 /* if 2nd param true, text mode if 2nd param false */ 194 int gp_setmode_binary(FILE * pfile, bool mode); 195 196 typedef enum { 197 gp_combine_small_buffer = -1, 198 gp_combine_cant_handle = 0, 199 gp_combine_success = 1 200 } gp_file_name_combine_result; 201 202 /* 203 * Combine a file name with a prefix. 204 * Concatenates two paths and reduce parten references and current 205 * directory references from the concatenation when possible. 206 * The trailing zero byte is being added. 207 * Various platforms may share this code. 208 */ 209 gp_file_name_combine_result gp_file_name_combine(const char *prefix, uint plen, 210 const char *fname, uint flen, bool no_sibling, char *buffer, uint *blen); 211 212 /* -------------- Helpers for gp_file_name_combine_generic ------------- */ 213 /* Platforms, which do not call gp_file_name_combine_generic, */ 214 /* must stub the helpers against linkage problems. */ 215 216 /* Return length of root prefix of the file name, or zero. */ 217 /* unix: length("/") */ 218 /* Win: length("c:/") or length("//computername/cd:/") */ 219 /* mac: length("volume:") */ 220 /* VMS: length("device:[root.][" */ 221 uint gp_file_name_root(const char *fname, uint len); 222 223 /* Check whether a part of file name starts (ends) with a separator. */ 224 /* Must return the length of the separator.*/ 225 /* If the 'len' is negative, must search in backward direction. */ 226 /* unix: '/' */ 227 /* Win: '/' or '\' */ 228 /* mac: ':' except "::" */ 229 /* VMS: smart - see the implementation */ 230 uint gs_file_name_check_separator(const char *fname, int len, const char *item); 231 232 /* Check whether a part of file name is a parent reference. */ 233 /* unix, Win: equal to ".." */ 234 /* mac: equal to ":" */ 235 /* VMS: equal to "." */ 236 bool gp_file_name_is_parent(const char *fname, uint len); 237 238 /* Check if a part of file name is a current directory reference. */ 239 /* unix, Win: equal to "." */ 240 /* mac: equal to "" */ 241 /* VMS: equal to "" */ 242 bool gp_file_name_is_current(const char *fname, uint len); 243 244 /* Returns a string for referencing the current directory. */ 245 /* unix, Win: "." */ 246 /* mac: ":" */ 247 /* VMS: "" */ 248 const char *gp_file_name_current(void); 249 250 /* Returns a string for separating a file name item. */ 251 /* unix, Win: "/" */ 252 /* mac: ":" */ 253 /* VMS: "]" */ 254 const char *gp_file_name_separator(void); 255 256 /* Returns a string for separating a directory item. */ 257 /* unix, Win: "/" */ 258 /* mac: ":" */ 259 /* VMS: "." */ 260 const char *gp_file_name_directory_separator(void); 261 262 /* Returns a string for representing a parent directory reference. */ 263 /* unix, Win: ".." */ 264 /* mac: ":" */ 265 /* VMS: "." */ 266 const char *gp_file_name_parent(void); 267 268 /* Answer whether the platform allows parent refenences. */ 269 /* unix, Win, Mac: yes */ 270 /* VMS: no. */ 271 bool gp_file_name_is_partent_allowed(void); 272 273 /* Answer whether an empty item is meanful in file names on the platform. */ 274 /* unix, Win: no */ 275 /* mac: yes */ 276 /* VMS: yes */ 277 bool gp_file_name_is_empty_item_meanful(void); 278 279 /* Read a 'resource' stored in a special database indexed by a 32 bit */ 280 /* 'type' and 16 bit 'id' in an extended attribute of a file. The is */ 281 /* primarily for accessing fonts on MacOS, which classically used this */ 282 /* format. Presumedly a 'nop' on systems that don't support Apple HFS. */ 283 int gp_read_macresource(byte *buf, const char *fname, 284 const uint type, const ushort id); 285 286 287 /* ------ persistent cache interface ------ */ 288 289 /* 290 * This is used for access to data cached between invocations of 291 * Ghostscript. It is generally used for saving reusable data that 292 * is expensive to compute. Concurrent access by multiple instances 293 * is safe. Because of this care should be taken to use a new data 294 * type when the format of the cached data changes. 295 * 296 * Generic data buffers are stored under a combination of type and 297 * key. It is up the to client to interpret the data buffer appropriately. 298 * An insert overwrites any previous entry under that type and key. 299 * A query if successful uses the passed callback to allocate a buffer 300 * and fills it with the retrieved data. The caller is thus responsible 301 * for the buffer's memory management. 302 * 303 * See zmisc.c for postscript test operators and an example implementation. 304 */ 305 306 /* return 0 on successful insert, non-zero otherwise */ 307 int gp_cache_insert(int type, byte *key, int keylen, void *buffer, int buflen); 308 309 /* return the length of the buffer on success, a negative value otherwise */ 310 typedef void *(*gp_cache_alloc)(void *userdata, int bytes); 311 int gp_cache_query(int type, byte* key, int keylen, void **buffer, 312 gp_cache_alloc alloc, void *userdata); 313 314 /* cache data types */ 315 #define GP_CACHE_TYPE_TEST 0 316 #define GP_CACHE_TYPE_FONTMAP 1 317 #define GP_CACHE_TYPE_WTS 2 318 319 320 /* ------ Printer accessing ------ */ 321 322 /* 323 * Open a connection to a printer. A null file name means use the standard 324 * printer connected to the machine, if any. Note that this procedure is 325 * called only if the original file name (normally the value of the 326 * OutputFile device parameter) was an ordinary file (not stdout, a pipe, or 327 * other %filedevice%file name): stdout is handled specially, and other 328 * values of filedevice are handled by calling the fopen procedure 329 * associated with that kind of "file". 330 * 331 * Note that if the file name is null (0-length) and a default printer is 332 * available, the file name may be replaced with the name of a scratch file 333 * for spooling. If the file name is null and no default printer is 334 * available, this procedure returns 0. 335 */ 336 FILE *gp_open_printer(char fname[gp_file_name_sizeof], int binary_mode); 337 338 /* 339 * Close the connection to the printer. Note that this is only called 340 * if the original file name was an ordinary file (not stdout, a pipe, 341 * or other %filedevice%file name): stdout is handled specially, and other 342 * values of filedevice are handled by calling the fclose procedure 343 * associated with that kind of "file". 344 */ 345 void gp_close_printer(FILE * pfile, const char *fname); 346 347 /* ------ File enumeration ------ */ 348 349 #ifndef file_enum_DEFINED /* also defined in iodev.h */ 350 # define file_enum_DEFINED 351 typedef struct file_enum_s file_enum; 352 #endif 353 354 /* 355 * Begin an enumeration. pat is a C string that may contain *s or ?s. 356 * The implementor should copy the string to a safe place. 357 * If the operating system doesn't support correct, arbitrarily placed 358 * *s and ?s, the implementation should modify the string so that it 359 * will return a conservative superset of the request, and then use 360 * the string_match procedure to select the desired subset. E.g., if the 361 * OS doesn't implement ? (single-character wild card), any consecutive 362 * string of ?s should be interpreted as *. Note that \ can appear in 363 * the pattern also, as a quoting character. 364 */ 365 file_enum *gp_enumerate_files_init(const char *pat, uint patlen, 366 gs_memory_t * memory); 367 368 /* 369 * Return the next file name in the enumeration. The client passes in 370 * a scratch string and a max length. If the name of the next file fits, 371 * the procedure returns the length. If it doesn't fit, the procedure 372 * returns max length +1. If there are no more files, the procedure 373 * returns -1. 374 */ 375 uint gp_enumerate_files_next(file_enum * pfen, char *ptr, uint maxlen); 376 377 /* 378 * Clean up a file enumeration. This is only called to abandon 379 * an enumeration partway through: ...next should do it if there are 380 * no more files to enumerate. This should deallocate the file_enum 381 * structure and any subsidiary structures, strings, buffers, etc. 382 */ 383 void gp_enumerate_files_close(file_enum * pfen); 384 385 386 /* ------ Font enumeration ------ */ 387 388 /* This is used to query the native os for a list of font names and 389 * corresponding paths. The general idea is to save the hassle of 390 * building a custom fontmap file 391 */ 392 393 /* allocate and initialize the iterator 394 returns a pointer to its local state or NULL on failure */ 395 void *gp_enumerate_fonts_init(gs_memory_t *mem); 396 397 /* get the next element in the font enumeration 398 Takes a pointer to its local state and pointers in which to 399 return C strings. The string 'name' is the font name, 'path' 400 is the access path for the font resource. The returned strings 401 are only safe to reference until until the next call. 402 Returns 0 when no more fonts are available, a positive value 403 on success, or negative value on error. */ 404 int gp_enumerate_fonts_next(void *enum_state, char **fontname, char **path); 405 406 /* clean up and deallocate the iterator */ 407 void gp_enumerate_fonts_free(void *enum_state); 408 409 #endif /* gp_INCLUDED */ 410