2 * Copyright (C) 2012, 2013
5 * Permission is hereby granted, free of charge, to any person obtaining a copy of
6 * this software and associated documentation files (the "Software"), to deal in
7 * the Software without restriction, including without limitation the rights to
8 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
9 * of the Software, and to permit persons to whom the Software is furnished to do
10 * so, subject to the following conditions:
12 * The above copyright notice and this permission notice shall be included in all
13 * copies or substantial portions of the Software.
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24 #ifndef GMQCC_PLATFORM_HDR
25 #define GMQCC_PLATFORM_HDR
27 #ifndef GMQCC_PLATFORM_HEADER
28 # error "This header shouldn't be included!"
31 #undef GMQCC_PLATFORM_HEADER
37 # ifndef STDERR_FILENO
38 # define STDERR_FILENO 2
40 # ifndef STDOUT_FILENO
41 # define STDOUT_FILENO 1
44 # define _WIN32_LEAN_AND_MEAN
51 unsigned short d_reclen;
52 unsigned short d_namlen;
53 char d_name[FILENAME_MAX];
57 struct _finddata_t dd_dta;
66 # endif /*! S_ISDIR */
67 # define S_ISDIR(X) ((X)&_S_IFDIR)
70 # endif /*!__MINGW32__*/
72 # include <sys/types.h>
73 # include <sys/stat.h>
79 * Function: platform_vsnprintf
80 * Write formatted output using a pointer to a lis of arguments.
83 * buffer - Storage location for output.
84 * bytes - Maximum number of characters to write.
85 * format - Format specification.
86 * arg - Variable argument list.
89 * The number of characters written if the number of characters to write
90 * is less than or equal to `bytes`; if the number of characters to write
91 * is greater than `bytes`, this function returns -1 indicating that the
92 * output has been truncated. The return value does not include the
93 * terminating null, if one is written.
96 * Function takes pointer to an argument list, then formats the data,
97 * and writes up to `bytes` characters to the memory pointed to by
98 * `buffer`. If there is room at the end (that is, if the number of
99 * character to write is less than `bytes`), the buffer will be null-terminated.
101 int platform_vsnprintf(char *buffer, size_t bytes, const char *format, va_list arg);
104 * Function: platform_vsscanf
105 * Reads formatted data from a string.
108 * buffer - Stored data to read.
109 * format - Format specification.
110 * arg - Variable argument list.
113 * The number of fields that are successfully converted and assigned;
114 * the return value does not include fields that were read but not
115 * assigned. A return vlaue of 0 indicated that no fields were assigned.
116 * The return value if EOF for error or if the end of the string is
117 * reached before the first conversion.
120 * Reads data from `buffer` into the locations that are given by each
121 * argument in the `arg` argument list. Every argument in the list must
122 * be a pointer to a variable that has a type that corresponds to a
123 * type specifier in `format`. The `format` argument controls th
124 * interpretation of the input fields and has the same form and function
125 * as the `format` argument for the *scanf* function. If copying takes
126 * place between strings that overlap, the behaviour is undefined.
128 int platform_vsscanf(const char *buffer, const char *format, va_list arg);
131 * Function: platform_localtime
132 * Convert a time value and correct for the local time zone.
135 * timer - Pointer to stored time.
138 * A pointer to a structure result, or NULL if the date passed to
139 * the function is before midnight, January 1, 1970.
141 const struct tm *platform_localtime(const time_t *timer);
144 * Function: platform_ctime
145 * Convert a time value to a string and adjust for local time zone
149 * timer - Pointer to stored time.
152 * Pointer to the character string result. NULL will be returned if time
153 * represents a date before midnight, January 1, 1970, UTC.
156 * Converts a time value stored as a `time_t` value into a chracter string.
157 * The `timer` value is usually obtained from a call to *time*, which returns
158 * the number of seconds since midnight, January 1, 1970 UTC. The return
159 * value of the string contains exactly 26 characters. A 24-hour clock is used.
160 * All fields have constant width. The newline chracter and the null character
161 * occupy the last two positions of the string. The converted character string
162 * is also adjusted according to the local time zone settings.
164 const char *platform_ctime(const time_t *timer);
167 * Function: platform_strncat
168 * Append characters of a string.
171 * dest - Null terminated destination string
172 * src - Source string
173 * num - Number of characters to append
176 * Pointer to the destination string. No return value is used to indicate
180 * Function appends, at mode, the first `num` characters of `src` to
181 * `dest`. The initial character of `src` overwrites the terminating
182 * null chracter of `dest`. If a null character appears in `src` before
183 * `num` chracters are appended, `platform_strncat` appends all chracters
184 * from `src`, up to the null chracter. If `num` is greater than the
185 * length of `src`, the length of `src` is used in place of `num`.
187 char *platform_strncat(char *dest, const char *src, size_t num);
190 * Function: platform_tmpnam
191 * Generates names you can use to create temporary files.
194 * str - Pointer that will hold the generated name and will be identical
195 * to the name returned by the function. This is a convenient way
196 * to save the generated name.
199 * Pointer to the name generate or *NULL* if there is a failure. Failure
200 * can occur if you attempt more than TMP_MAX calls.
203 * Returns a name unique in the current workign directory.
205 const char *platform_tmpnam(char *str);
208 * Function: platform_getenv
209 * Get a value from the current enviroment.
212 * var - Enviroment variable name
215 * A pointer to the enviroment table entry containing `var. It's not
216 * safe to modify the value of the enviroment variable using the returned
217 * pointer. The return value is *NULL* if `var` is not found in the
220 const char *platform_getenv(char *var);
223 * Function: platform_vasprintf
224 * Print to allocated string
227 * dat - Pointer to pointer to store allocated data.
228 * fmt - Format specification.
229 * args - Variable argument list.
232 * Number of character written, -1 is used to indicate an error.
235 * Allocate a string large enough to hold the output including
236 * the terminating null character than write formatted output
237 * to it using format specification.
239 int platform_vasprintf(char **dat, const char *fmt, va_list args);
242 * Function: platform_vfprintf
243 * Write formatted output using a pointer to a list of arguments.
246 * stream - Pointer to stream.
247 * format - Format specification.
248 * atrg - Variable argument list.
251 * Number of characters written, not including the terminating null
252 * character, or a negitive value if an output error occurs. -1 is
253 * also used to indicate an error.
256 * Takes a pointer to an argument list, then formats and writes the
257 * given data to `stream`.
259 int platform_vfprintf(FILE *stream, const char *format, va_list arg);
262 * Function: platform_strcat
263 * Append characters of a string.
266 * dest - Null terminated destination string
267 * src - Source string
270 * Pointer to the destination string. No return value is used to indicate
274 * Appens `src` to `dest` and terminates with resulting null character.
275 * The initial character of `src` overwrites the terminating null
276 * character of `dest`. The behaviour of platform_strcat is undefined
277 * if the source and destination string overlap.
279 char *platform_strcat(char *dest, const char *src);
282 * Function: platform_strncpy
283 * Copys characters of one string to another.
286 * dest - Destination string.
287 * src - Source string.
288 * num - Number of characters to be copied.
291 * `dest`. No return value is reserved to indicate an error.
294 * Copies the initial characters of `src` to `dest` and returns `dest`.
295 * If `num` is less than or equal to the length of `src1 a null character
296 * is not appended automatically to the copied string. If `num` is greater
297 * than the length of `src`, the destination string is padded with null
298 * characters up to length `num`. The behaviour of this function is undefined
299 * if the source and destination strings overlap.
301 char *platform_strncpy(char *dest, const char *src, size_t num);
304 * Function: platform_strerror
305 * Get a system error message
308 * err - Error number.
311 * A pointer to the error message
313 const char *platform_strerror(int err);
316 * Function: platform_fopen
320 * filename - File name.
321 * mode - Kind of access that's enabled.
324 * A pointer to the open file. A null pointer value indicates an error.
326 FILE *platform_fopen(const char *filename, const char *mode);
329 * Function: platform_fread
330 * Reads data from a stream
333 * ptr - Storage location for data.
334 * size - Item size in bytes.
335 * count - Maximum number of items to be read.
336 * stream - Pointer to stream
339 * The number of full items actually read, which may be less than `count`
340 * if an error occurs or if the end of the file is encountered before
341 * reaching `count`. If `size` or `count` is 0, `platform_fread`
342 * returns 0 and the buffer contents are unchanged.
344 size_t platform_fread(void *ptr, size_t size, size_t count, FILE *stream);
347 * Function: platform_fwrite
348 * Writes data to a stream
351 * ptr - Pointer to data to be written.
352 * size - Item size in bytes.
353 * count - Maximum number of items to be read.
354 * stream - Pointer to stream
357 * The number of full items actually written, which may be less than
358 * `count` if an error occurs. Also, if an error occurs, the
359 * file-position indicator cannot be determined.
362 * Writes up to `count` items, of `size` length each, from `ptr` to the
363 * output stream. The file pointer associated with stream (if there is one)
364 * is incremented by the number of bytes actually written.
366 size_t platform_fwrite(const void *ptr, size_t size, size_t count, FILE *stream);
369 * Function: platform_fflush
373 * stream - Pointer to stream
376 * 0 value if the buffer was succesffuly flushed. The value 0 is also
377 * returned in cases in which the specified stream has no buffer or is
378 * open for reading only. A return value of *EOF* indicates an error.
381 * Flushes a stream. If the file associated with stream is open for output,
382 * platform_fflush writes to that file the contents of the buffer
383 * associated with the stream. If the stream is open for input,
384 * platform_fflush clears the contents of the buffer. platform_fflush
385 * negates the effect of any prior call to ungetc against stream. Also,
386 * platform_fflush(NULL) flushes all streams opened for output.
387 * The stream remains open after the call. platform_fflush has no effect
388 * on an unbuffered stream.
390 int platform_fflush(FILE *stream);
393 * Function: platform_fclose
397 * stream - Pointer to stream.
400 * 0 value. *EOF* is used to indicate an error.
405 int platform_fclose(FILE *stream);
408 * Function: platform_ferror
409 * Tests for an error on a stream.
412 * stream - Pointer to stream.
415 * If not error has occured on `stream`, 0 value is returned, otherwise
416 * it returns a nonzero value.
419 * Tests for a reading or writing error on the file associated with `stream`.
420 * If an error has occured, the error indicator for the stream remains set
421 * until the stream is closed or rewound.
423 int platform_ferror(FILE *stream);
426 * Function: platform_fgetc
427 * Read a character from a stream.
430 * stream - Pointer to a stream.
433 * The chracter read as an int or EOF to indicate an error or end-of-file.
436 * Reads a single chracter from the current position of the file associated
437 * with `stream`. Than increments that position. If the steam is at the end
438 * of the file, the end-of-file indicator for the stream is set.
440 int platform_fgetc(FILE *stream);
443 * Function: platform_fputs
444 * Write a string to a stream
447 * str - Output string.
448 * stream - Pointer to stream.
451 * Non-negative value if successful. EOF is used to indicate an error.
454 * Copies `str` to the output stream at the current position.
456 int platform_fputs(const char *str, FILE *stream);
459 * Function: platform_fseek
460 * Moves the file pointer to a specified location.
463 * stream - Pointer to stream.
464 * offset - Number of bytes from origin to offset.
465 * origin - Initital position.
468 * 0 value, nonzero values are used to indicate an error.
471 * Moves the file pointer (if any) associated with stream to a new
472 * location that is offset bytes from origin.
473 * The next operation on the stream takes place at the new location.
474 * On a stream open for update, the next operation can be either a
477 int platform_fseek(FILE *stream, long offset, int origin);
480 * Function: platform_ftell
481 * Gets the current position of a file pointer
484 * stream - Pointer to stream
487 * Current file position. May not reflect physical byte offset, e.g
488 * systems where read-mode does carriage return-linefeed translation.
489 * -1 value is used to indivate an error.
491 long platform_ftell(FILE *stream);
494 * Function: platform_mkdir
498 * path - Path to create
499 * mode - The mode of the directory (implementation defined)
502 * 0 value. -1 value is used to indicate an error. On error no
503 * directory shall be created.
506 * Shall create a new empty directory with with the name path specified
509 int platform_mkdir(const char *path, int mode);
512 * Function: platform_opendir
516 * path - Path to the directory to open
519 * Pointer to an object of type *DIR*. A null pointer value indicates
523 * Shall open a directory stream corresponding to the directory named by
524 * the `path` argument. The directory stream is positioned at the first entry.
526 DIR *platform_opendir(const char *path);
529 * Function: platform_closedir
530 * Close a directory stream
533 * dir - Pointer to directory stream
536 * 0 value. A -1 value indicated an error.
539 * Shall close the directory stream referred to by the argument
540 * `dir`. Upon return, the value of `dir` may no longer point to
541 * an accessible object of the type *DIR*.
543 int platform_closedir(DIR *dir);
546 * Function: platform_readdir
550 * dir - Pointer to directory stream
553 * Pointer to an object of type `struct dirent`. A null pointer value
554 * indicates an error.
557 * When the end of the directory is encountered, a null pointer is
560 struct dirent *platform_readdir(DIR *dir);
563 * Function: platform_isatty
564 * Determines whether a file descriptor is associated with a character
568 * A nonzero value if the descriptor is associated with a character
569 * device. Otherwise `platform_isatty` returns 0.
571 int platform_isatty(int fd);