1
/* Copyright (C) 2001-2006 Artifex Software, Inc.
4
This software is provided AS-IS with no warranty, either express or
7
This software is distributed under license and may not be copied, modified
8
or distributed except as expressly authorized under the terms of that
9
license. Refer to licensing information at http://www.artifex.com/
10
or contact Artifex Software, Inc., 7 Mt. Lassen Drive - Suite A-134,
11
San Rafael, CA 94903, U.S.A., +1(415)492-9861, for further information.
14
/* $Id: gp.h 8022 2007-06-05 22:23:38Z giles $ */
15
/* Interface to platform-specific routines */
16
/* Requires gsmemory.h */
23
* This file defines the interface to ***ALL*** platform-specific routines,
24
* with the exception of the thread/synchronization interface (gpsync.h)
25
* and getenv (gpgetenv.h). The implementations are in gp_*.c files
26
* specific to each platform. We try very hard to keep this list short!
29
* gp_getenv is declared in a separate file because a few places need it
30
* and don't want to include any of the other gs definitions.
34
* The prototype for gp_readline is in srdline.h, since it is shared with
40
* int64_t is used in the 64 bits file access.
44
/* ------ Initialization/termination ------ */
47
* This routine is called early in the initialization.
48
* It should do as little as possible. In particular, it should not
49
* do things like open display connections: that is the responsibility
50
* of the display device driver.
55
* This routine is called just before the program exits (normally or
56
* abnormally). It too should do as little as possible.
58
void gp_exit(int exit_status, int code);
61
* Exit the program. Normally this just calls the `exit' library procedure,
62
* but it does something different on a few platforms.
64
void gp_do_exit(int exit_status);
66
/* ------ Miscellaneous ------ */
69
* Get the string corresponding to an OS error number.
70
* If no string is available, return NULL. The caller may assume
71
* the string is allocated statically and permanently.
73
const char *gp_strerror(int);
75
/* ------ Date and time ------ */
78
* Read the current time (in seconds since an implementation-defined epoch)
79
* into ptm[0], and fraction (in nanoseconds) into ptm[1].
81
void gp_get_realtime(long ptm[2]);
84
* Read the current user CPU time (in seconds) into ptm[0],
85
* and fraction (in nanoseconds) into ptm[1].
87
void gp_get_usertime(long ptm[2]);
89
/* ------ Reading lines from stdin ------ */
92
* These routines are intended to provide an abstract interface to GNU
93
* readline or to other packages that offer enhanced line-reading
98
* Allocate a state structure for line reading. This is called once at
99
* initialization. *preadline_data is an opaque pointer that is passed
100
* back to gp_readline and gp_readline_finit.
102
int gp_readline_init(void **preadline_data, gs_memory_t *mem);
105
* See srdline.h for the definition of sreadline_proc.
107
int gp_readline(stream *s_in, stream *s_out, void *readline_data,
108
gs_const_string *prompt, gs_string *buf,
109
gs_memory_t *bufmem, uint *pcount, bool *pin_eol,
110
bool (*is_stdin)(const stream *));
113
* Free a readline state.
115
void gp_readline_finit(void *readline_data);
117
/* ------ Reading from stdin, unbuffered if possible ------ */
119
/* Read bytes from stdin, using unbuffered if possible.
120
* Store up to len bytes in buf.
121
* Returns number of bytes read, or 0 if EOF, or -ve if error.
122
* If unbuffered is NOT possible, fetch 1 byte if interactive
123
* is non-zero, or up to len bytes otherwise.
124
* If unbuffered is possible, fetch at least 1 byte (unless error or EOF)
125
* and any additional bytes that are available without blocking.
127
int gp_stdin_read(char *buf, int len, int interactive, FILE *f);
129
/* ------ Screen management ------ */
132
* The following are only relevant for X Windows.
135
/* Get the environment variable that specifies the display to use. */
136
const char *gp_getenv_display(void);
138
/* ------ File naming and accessing ------ */
141
* Define the maximum size of a file name returned by gp_open_scratch_file
142
* or gp_open_printer. (This should really be passed as an additional
143
* parameter, but it would break too many clients to make this change now.)
144
* Note that this is the size of the buffer, not the maximum number of
145
* characters: the latter is one less, because of the terminating \0.
147
#define gp_file_name_sizeof 260 /* == MAX_PATH on Windows */
149
/* Define the character used for separating file names in a list. */
150
extern const char gp_file_name_list_separator;
152
/* Define the default scratch file name prefix. */
153
extern const char gp_scratch_file_name_prefix[];
155
/* Define the name of the null output file. */
156
extern const char gp_null_file_name[];
158
/* Define the name that designates the current directory. */
159
extern const char gp_current_directory_name[];
161
/* Define the string to be concatenated with the file mode */
162
/* for opening files without end-of-line conversion. */
163
/* This is always either "" or "b". */
164
extern const char gp_fmode_binary_suffix[];
166
/* Define the file modes for binary reading or writing. */
167
/* (This is just a convenience: they are "r" or "w" + the suffix.) */
168
extern const char gp_fmode_rb[];
169
extern const char gp_fmode_wb[];
172
* gp_open_scratch_file: Create a scratch file.
173
* @prefix: Name prefix.
174
* @fname: Where to store filename of newly created file.
175
* @mode: File access mode (in fopen syntax).
177
* Creates a scratch (temporary) file in the filesystem. The exact
178
* location and name of the file is platform dependent, but in general
179
* uses @prefix as a prefix. If @prefix is not absolute, then choose
180
* an appropriate system directory, usually as determined from
181
* gp_gettmpdir(), followed by a path as returned from a system call.
183
* Implementations should make sure that
185
* Return value: Opened file object, or NULL on error.
187
FILE *gp_open_scratch_file(const char *prefix,
188
char fname[gp_file_name_sizeof],
191
/* Open a file with the given name, as a stream of uninterpreted bytes. */
192
FILE *gp_fopen(const char *fname, const char *mode);
194
/* Force given file into binary mode (no eol translations, etc) */
195
/* if 2nd param true, text mode if 2nd param false */
196
int gp_setmode_binary(FILE * pfile, bool mode);
199
gp_combine_small_buffer = -1,
200
gp_combine_cant_handle = 0,
201
gp_combine_success = 1
202
} gp_file_name_combine_result;
205
* Combine a file name with a prefix.
206
* Concatenates two paths and reduce parten references and current
207
* directory references from the concatenation when possible.
208
* The trailing zero byte is being added.
209
* Various platforms may share this code.
211
gp_file_name_combine_result gp_file_name_combine(const char *prefix, uint plen,
212
const char *fname, uint flen, bool no_sibling, char *buffer, uint *blen);
214
/* -------------- Helpers for gp_file_name_combine_generic ------------- */
215
/* Platforms, which do not call gp_file_name_combine_generic, */
216
/* must stub the helpers against linkage problems. */
218
/* Return length of root prefix of the file name, or zero. */
219
/* unix: length("/") */
220
/* Win: length("c:/") or length("//computername/cd:/") */
221
/* mac: length("volume:") */
222
/* VMS: length("device:[root.][" */
223
uint gp_file_name_root(const char *fname, uint len);
225
/* Check whether a part of file name starts (ends) with a separator. */
226
/* Must return the length of the separator.*/
227
/* If the 'len' is negative, must search in backward direction. */
229
/* Win: '/' or '\' */
230
/* mac: ':' except "::" */
231
/* VMS: smart - see the implementation */
232
uint gs_file_name_check_separator(const char *fname, int len, const char *item);
234
/* Check whether a part of file name is a parent reference. */
235
/* unix, Win: equal to ".." */
236
/* mac: equal to ":" */
237
/* VMS: equal to "." */
238
bool gp_file_name_is_parent(const char *fname, uint len);
240
/* Check if a part of file name is a current directory reference. */
241
/* unix, Win: equal to "." */
242
/* mac: equal to "" */
243
/* VMS: equal to "" */
244
bool gp_file_name_is_current(const char *fname, uint len);
246
/* Returns a string for referencing the current directory. */
250
const char *gp_file_name_current(void);
252
/* Returns a string for separating a file name item. */
256
const char *gp_file_name_separator(void);
258
/* Returns a string for separating a directory item. */
262
const char *gp_file_name_directory_separator(void);
264
/* Returns a string for representing a parent directory reference. */
265
/* unix, Win: ".." */
268
const char *gp_file_name_parent(void);
270
/* Answer whether the platform allows parent refenences. */
271
/* unix, Win, Mac: yes */
273
bool gp_file_name_is_partent_allowed(void);
275
/* Answer whether an empty item is meanful in file names on the platform. */
279
bool gp_file_name_is_empty_item_meanful(void);
281
/* Read a 'resource' stored in a special database indexed by a 32 bit */
282
/* 'type' and 16 bit 'id' in an extended attribute of a file. The is */
283
/* primarily for accessing fonts on MacOS, which classically used this */
284
/* format. Presumedly a 'nop' on systems that don't support Apple HFS. */
285
int gp_read_macresource(byte *buf, const char *fname,
286
const uint type, const ushort id);
289
/* ------ persistent cache interface ------ */
292
* This is used for access to data cached between invocations of
293
* Ghostscript. It is generally used for saving reusable data that
294
* is expensive to compute. Concurrent access by multiple instances
295
* is safe. Because of this care should be taken to use a new data
296
* type when the format of the cached data changes.
298
* Generic data buffers are stored under a combination of type and
299
* key. It is up the to client to interpret the data buffer appropriately.
300
* An insert overwrites any previous entry under that type and key.
301
* A query if successful uses the passed callback to allocate a buffer
302
* and fills it with the retrieved data. The caller is thus responsible
303
* for the buffer's memory management.
305
* See zmisc.c for postscript test operators and an example implementation.
308
/* return 0 on successful insert, non-zero otherwise */
309
int gp_cache_insert(int type, byte *key, int keylen, void *buffer, int buflen);
311
/* return the length of the buffer on success, a negative value otherwise */
312
typedef void *(*gp_cache_alloc)(void *userdata, int bytes);
313
int gp_cache_query(int type, byte* key, int keylen, void **buffer,
314
gp_cache_alloc alloc, void *userdata);
316
/* cache data types */
317
#define GP_CACHE_TYPE_TEST 0
318
#define GP_CACHE_TYPE_FONTMAP 1
319
#define GP_CACHE_TYPE_WTS_SIZE 2
320
#define GP_CACHE_TYPE_WTS_CELL 3
323
/* ------ Printer accessing ------ */
326
* Open a connection to a printer. A null file name means use the standard
327
* printer connected to the machine, if any. Note that this procedure is
328
* called only if the original file name (normally the value of the
329
* OutputFile device parameter) was an ordinary file (not stdout, a pipe, or
330
* other %filedevice%file name): stdout is handled specially, and other
331
* values of filedevice are handled by calling the fopen procedure
332
* associated with that kind of "file".
334
* Note that if the file name is null (0-length) and a default printer is
335
* available, the file name may be replaced with the name of a scratch file
336
* for spooling. If the file name is null and no default printer is
337
* available, this procedure returns 0.
339
FILE *gp_open_printer(char fname[gp_file_name_sizeof], int binary_mode);
342
* Close the connection to the printer. Note that this is only called
343
* if the original file name was an ordinary file (not stdout, a pipe,
344
* or other %filedevice%file name): stdout is handled specially, and other
345
* values of filedevice are handled by calling the fclose procedure
346
* associated with that kind of "file".
348
void gp_close_printer(FILE * pfile, const char *fname);
350
/* ------ File enumeration ------ */
352
#ifndef file_enum_DEFINED /* also defined in iodev.h */
353
# define file_enum_DEFINED
354
typedef struct file_enum_s file_enum;
358
* Begin an enumeration. pat is a C string that may contain *s or ?s.
359
* The implementor should copy the string to a safe place.
360
* If the operating system doesn't support correct, arbitrarily placed
361
* *s and ?s, the implementation should modify the string so that it
362
* will return a conservative superset of the request, and then use
363
* the string_match procedure to select the desired subset. E.g., if the
364
* OS doesn't implement ? (single-character wild card), any consecutive
365
* string of ?s should be interpreted as *. Note that \ can appear in
366
* the pattern also, as a quoting character.
368
file_enum *gp_enumerate_files_init(const char *pat, uint patlen,
369
gs_memory_t * memory);
372
* Return the next file name in the enumeration. The client passes in
373
* a scratch string and a max length. If the name of the next file fits,
374
* the procedure returns the length. If it doesn't fit, the procedure
375
* returns max length +1. If there are no more files, the procedure
378
uint gp_enumerate_files_next(file_enum * pfen, char *ptr, uint maxlen);
381
* Clean up a file enumeration. This is only called to abandon
382
* an enumeration partway through: ...next should do it if there are
383
* no more files to enumerate. This should deallocate the file_enum
384
* structure and any subsidiary structures, strings, buffers, etc.
386
void gp_enumerate_files_close(file_enum * pfen);
389
/* ------ Font enumeration ------ */
391
/* This is used to query the native os for a list of font names and
392
* corresponding paths. The general idea is to save the hassle of
393
* building a custom fontmap file
396
/* allocate and initialize the iterator
397
returns a pointer to its local state or NULL on failure */
398
void *gp_enumerate_fonts_init(gs_memory_t *mem);
400
/* get the next element in the font enumeration
401
Takes a pointer to its local state and pointers in which to
402
return C strings. The string 'name' is the font name, 'path'
403
is the access path for the font resource. The returned strings
404
are only safe to reference until until the next call.
405
Returns 0 when no more fonts are available, a positive value
406
on success, or negative value on error. */
407
int gp_enumerate_fonts_next(void *enum_state, char **fontname, char **path);
409
/* clean up and deallocate the iterator */
410
void gp_enumerate_fonts_free(void *enum_state);
412
/* --------- 64 bit file access ----------- */
414
/* The following functions are analogues of ones with
415
same name without the "_64" suffix.
416
They perform same function with allowing big files
417
(over 4 gygabytes length).
419
If the platform does not allow big files,
420
these functions are mapped to regular file i/o functions.
421
On 64 bits platforms they work same as
422
regular file i/o functions.
424
We continue using the old file i/o functions
425
because most files do not need 64 bits access.
426
The upgrading of old code to the new 64 bits access
427
to be done step by step on real necessity,
428
with replacing old function names with
429
new function names through code,
430
together with providing the int64_t type for storing
431
file offsets in intermediate structures and variables.
433
We assume that the result of 64 bits variant of 'ftell'
434
can be represented in int64_t on all platforms,
435
rather the result type of the native 64 bits function is
436
compiler dependent (__off_t on Linux, _off_t on Cygwin,
440
FILE *gp_fopen_64(const char *filename, const char *mode);
442
FILE *gp_open_scratch_file_64(const char *prefix,
443
char fname[gp_file_name_sizeof],
445
FILE *gp_open_printer_64(char fname[gp_file_name_sizeof], int binary_mode);
447
int64_t gp_ftell_64(FILE *strm);
449
int gp_fseek_64(FILE *strm, int64_t offset, int origin);
451
/* We don't define gp_fread_64, gp_fwrite_64,
452
because (1) known platforms allow regular fread, fwrite
453
to be applied to a file opened with O_LARGEFILE,
454
fopen64, etc.; (2) Ghostscript code does not
455
perform writing/reading a long (over 4gb) block
459
#endif /* gp_INCLUDED */
added
removed
src/gp.h
