Fix windows builds, add strip target for makefiles, update distro build makefiles...
[xonotic/gmqcc.git] / platform.h
1 /*
2  * Copyright (C) 2012, 2013
3  *     Dale Weiler
4  *
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:
11  *
12  * The above copyright notice and this permission notice shall be included in all
13  * copies or substantial portions of the Software.
14  *
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
21  * SOFTWARE.
22  */
23
24 #ifndef GMQCC_PLATFORM_HDR
25 #define GMQCC_PLATFORM_HDR
26
27 #ifndef GMQCC_PLATFORM_HEADER
28 #   error "This header shouldn't be included!"
29 #endif
30
31 #undef GMQCC_PLATFORM_HEADER
32 #include <stdarg.h>
33 #include <time.h>
34 #include <stdio.h>
35
36 #ifdef _WIN32
37 #   ifndef STDERR_FILENO
38 #       define STDERR_FILENO 2
39 #   endif
40 #   ifndef STDOUT_FILENO
41 #       define STDOUT_FILENO 1
42 #   endif
43 #   ifndef __MINGW32__
44 #       define _WIN32_LEAN_AND_MEAN
45 #       include <windows.h>
46 #       include <io.h>
47 #       include <fcntl.h>
48
49         struct dirent {
50             long               d_ino;
51             unsigned short     d_reclen;
52             unsigned short     d_namlen;
53             char               d_name[FILENAME_MAX];
54         };
55
56         typedef struct {
57             struct _finddata_t dd_dta;
58             struct dirent      dd_dir;
59             long               dd_handle;
60             int                dd_stat;
61             char               dd_name[1];
62         } DIR;
63 #   else
64 #       include <dirent.h>
65 #   endif /*!__MINGW32__*/
66
67 #   ifndef S_ISDIR
68 #       define S_ISDIR(X) ((X)&_S_IFDIR)
69 #   endif
70 #else
71 #   include <sys/types.h>
72 #   include <sys/stat.h>
73 #   include <unistd.h>
74 #   include <dirent.h>
75 #endif /*!_WIN32*/
76
77 /*
78  * Function: platform_vsnprintf
79  *  Write formatted output using a pointer to a lis of arguments.
80  *
81  * Parameters:
82  *  buffer - Storage location for output.
83  *  bytes  - Maximum number of characters to write.
84  *  format - Format specification.
85  *  arg    - Variable argument list.
86  *
87  * Returns:
88  *  The number of characters written if the number of characters to write
89  *  is less than or equal to `bytes`; if the number of characters to write
90  *  is greater than `bytes`, this function returns -1 indicating that the
91  *  output has been truncated. The return value does not include the
92  *  terminating null, if one is written.
93  *
94  * Remarks:
95  *  Function takes pointer to an argument list, then formats the data,
96  *  and writes up to `bytes` characters to the memory pointed to by
97  *  `buffer`. If there is room at the end (that is, if the number of
98  *  character to write is less than `bytes`), the buffer will be null-terminated.
99  */
100 int platform_vsnprintf(char *buffer, size_t bytes, const char *format, va_list arg);
101
102 /*
103  * Function: platform_vsscanf
104  *  Reads formatted data from a string.
105  *
106  * Parameters:
107  *  buffer - Stored data to read.
108  *  format - Format specification.
109  *  arg    - Variable argument list.
110  *
111  * Returns:
112  *  The number of fields that are successfully converted and assigned;
113  *  the return value does not include fields that were read but not
114  *  assigned. A return vlaue of 0 indicated that no fields were assigned.
115  *  The return value if EOF for error or if the end of the string is
116  *  reached before the first conversion.
117  *
118  * Remarks:
119  *  Reads data from `buffer` into the locations that are given by each
120  *  argument in the `arg` argument list. Every argument in the list must
121  *  be a pointer to a variable that has a type that corresponds to a
122  *  type specifier in `format`. The `format` argument controls th
123  *  interpretation of the input fields and has the same form and function
124  *  as the `format` argument for the *scanf* function. If copying takes
125  *  place between strings that overlap, the behaviour is undefined.
126  */
127 int platform_vsscanf(const char *buffer, const char *format, va_list arg);
128
129 /*
130  * Function: platform_localtime
131  *  Convert a time value and correct for the local time zone.
132  *
133  * Parameters
134  *  timer - Pointer to stored time.
135  *
136  * Returns:
137  *  A pointer to a structure result, or NULL if the date passed to
138  *  the function is before midnight, January 1, 1970.
139  */
140 const struct tm *platform_localtime(const time_t *timer);
141
142 /*
143  * Function: platform_ctime
144  *  Convert a time value to a string and adjust for local time zone
145  *  settings.
146  *
147  * Parameters:
148  *  timer - Pointer to stored time.
149  *
150  * Returns:
151  *  Pointer to the character string result. NULL will be returned if time
152  *  represents a date before midnight, January 1, 1970, UTC.
153  *
154  * Remarks:
155  *  Converts a time value stored as a `time_t` value into a chracter string.
156  *  The `timer` value is usually obtained from a call to *time*, which returns
157  *  the number of seconds since midnight, January 1, 1970 UTC. The return
158  *  value of the string contains exactly 26 characters. A 24-hour clock is used.
159  *  All fields have constant width. The newline chracter and the null character
160  *  occupy the last two positions of the string. The converted character string
161  *  is also adjusted according to the local time zone settings.
162  */
163 const char *platform_ctime(const time_t *timer);
164
165 /*
166  * Function: platform_strncat
167  *  Append characters of a string.
168  *
169  * Parameters:
170  *  dest - Null terminated destination string
171  *  src  - Source string
172  *  num  - Number of characters to append
173  *
174  * Returns:
175  *  Pointer to the destination string. No return value is used to indicate
176  *  an error.
177  *
178  * Remarks:
179  *  Function appends, at mode, the first `num` characters of `src` to
180  *  `dest`. The initial character of `src` overwrites the terminating
181  *  null chracter of `dest`. If a null character appears in `src` before
182  *  `num` chracters are appended, `platform_strncat` appends all chracters
183  *  from `src`, up to the null chracter. If `num` is greater than the
184  *  length of `src`, the length of `src` is used in place of `num`.
185  */
186 char *platform_strncat(char *dest, const char *src, size_t num);
187
188 /*
189  * Function: platform_tmpnam
190  *  Generates names you can use to create temporary files.
191  *
192  * Parameters:
193  *  str - Pointer that will hold the generated name and will be identical
194  *        to the name returned by the function. This is a convenient way
195  *        to save the generated name.
196  *
197  * Returns:
198  *  Pointer to the name generate or *NULL* if there is a failure. Failure
199  *  can occur if you attempt more than TMP_MAX calls.
200  *
201  * Remarks:
202  *  Returns a name unique in the current workign directory.
203  */
204 const char *platform_tmpnam(char *str);
205
206 /*
207  * Function: platform_getenv
208  *  Get a value from the current enviroment.
209  *
210  * Parameters:
211  *  var - Enviroment variable name
212  *
213  * Returns:
214  *  A pointer to the enviroment table entry containing `var. It's not
215  *  safe to modify the value of the enviroment variable using the returned
216  *  pointer. The return value is *NULL* if `var` is not found in the
217  *  enviroment table.
218  */
219 const char *platform_getenv(char *var);
220
221 /*
222  * Function: platform_vasprintf
223  *  Print to allocated string
224  *
225  * Parameters:
226  *  dat  - Pointer to pointer to store allocated data.
227  *  fmt  - Format specification.
228  *  args - Variable argument list.
229  *
230  * Returns:
231  *  Number of character written, -1 is used to indicate an error.
232  *
233  * Remarks:
234  *  Allocate a string large enough to hold the output including
235  *  the terminating null character than write formatted output
236  *  to it using format specification.
237  */
238 int platform_vasprintf(char **dat, const char *fmt, va_list args);
239
240 /*
241  * Function: platform_vfprintf
242  *  Write formatted output using a pointer to a list of arguments.
243  *
244  * Parameters:
245  *  stream - Pointer to stream.
246  *  format - Format specification.
247  *  atrg   - Variable argument list.
248  *
249  * Returns:
250  *  Number of characters written, not including the terminating null
251  *  character, or a negitive value if an output error occurs. -1 is
252  *  also used to indicate an error.
253  *
254  * Remarks:
255  *  Takes a pointer to an argument list, then formats and writes the
256  *  given data to `stream`.
257  */
258 int platform_vfprintf(FILE *stream, const char *format, va_list arg);
259
260 /*
261  * Function: platform_strcat
262  *  Append characters of a string.
263  *
264  * Parameters:
265  *  dest - Null terminated destination string
266  *  src  - Source string
267  *
268  * Returns:
269  *  Pointer to the destination string. No return value is used to indicate
270  *  an error.
271  *
272  * Remarks:
273  *  Appens `src` to `dest` and terminates with resulting null character.
274  *  The initial character of `src` overwrites the terminating null
275  *  character of `dest`. The behaviour of platform_strcat is undefined
276  *  if the source and destination string overlap.
277  */
278 char *platform_strcat(char *dest, const char *src);
279
280 /*
281  * Function: platform_strncpy
282  *  Copys characters of one string to another.
283  *
284  * Parameters:
285  *  dest - Destination string.
286  *  src  - Source string.
287  *  num  - Number of characters to be copied.
288  *
289  * Returns:
290  *  `dest`. No return value is reserved to indicate an error.
291  *
292  * Remarks:
293  *  Copies the initial characters of `src` to `dest` and returns `dest`.
294  *  If `num` is less than or equal to the length of `src1 a null character
295  *  is not appended automatically to the copied string. If `num` is greater
296  *  than the length of `src`, the destination string is padded with null
297  *  characters up to length `num`. The behaviour of this function is undefined
298  *  if the source and destination strings overlap.
299  */
300 char *platform_strncpy(char *dest, const char *src, size_t num);
301
302 /*
303  * Function: platform_strerror
304  *  Get a system error message
305  *
306  * Parameters:
307  *  err - Error number.
308  *
309  * Returns:
310  *  A pointer to the error message
311  */
312 const char *platform_strerror(int err);
313
314 /*
315  * Function: platform_fopen
316  *  Opens a file
317  *
318  * Parameters:
319  *  filename - File name.
320  *  mode     - Kind of access that's enabled.
321  *
322  * Returns:
323  *  A pointer to the open file. A null pointer value indicates an error.
324  */
325 FILE *platform_fopen(const char *filename, const char *mode);
326
327 /*
328  * Function: platform_fread
329  *  Reads data from a stream
330  *
331  * Parameters:
332  *  ptr    - Storage location for data.
333  *  size   - Item size in bytes.
334  *  count  - Maximum number of items to be read.
335  *  stream - Pointer to stream
336  *
337  * Returns:
338  *  The number of full items actually read, which may be less than `count`
339  *  if an error occurs or if the end of the file is encountered before
340  *  reaching `count`. If `size` or `count` is 0, `platform_fread`
341  *  returns 0 and the buffer contents are unchanged.
342  */
343 size_t platform_fread(void *ptr, size_t size, size_t count, FILE *stream);
344
345 /*
346  * Function: platform_fwrite
347  *  Writes data to a stream
348  *
349  * Parameters:
350  *  ptr    - Pointer to data to be written.
351  *  size   - Item size in bytes.
352  *  count  - Maximum number of items to be read.
353  *  stream - Pointer to stream
354  *
355  * Returns:
356  *  The number of full items actually written, which may be less than
357  *  `count` if an error occurs. Also, if an error occurs, the
358  *  file-position indicator cannot be determined.
359  *
360  * Remarks:
361  *  Writes up to `count` items, of `size` length each, from `ptr` to the
362  *  output stream. The file pointer associated with stream (if there is one)
363  *  is incremented by the number of bytes actually written.
364  */
365 size_t platform_fwrite(const void *ptr, size_t size, size_t count, FILE *stream);
366
367 /*
368  * Function: platform_fflush
369  *  Flushes a stream
370  *
371  * Parameters:
372  *  stream - Pointer to stream
373  *
374  * Returns:
375  *  0 value if the buffer was succesffuly flushed. The value 0 is also
376  *  returned in cases in which the specified stream has no buffer or is
377  *  open for reading only. A return value of *EOF* indicates an error.
378  *
379  * Remarks:
380  *  Flushes a stream. If the file associated with stream is open for output,
381  *  platform_fflush writes to that file the contents of the buffer
382  *  associated with the stream. If the stream is open for input,
383  *  platform_fflush clears the contents of the buffer. platform_fflush
384  *  negates the effect of any prior call to ungetc against stream. Also,
385  *  platform_fflush(NULL) flushes all streams opened for output.
386  *  The stream remains open after the call. platform_fflush has no effect
387  *  on an unbuffered stream.
388  */
389 int platform_fflush(FILE *stream);
390
391 /*
392  * Function: platform_fclose
393  *  Closes a stream.
394  *
395  * Parameters:
396  *  stream - Pointer to stream.
397  *
398  * Returns:
399  *  0 value. *EOF* is used to indicate an error.
400  *
401  * Remarks:
402  *  Closes a stream.
403  */
404 int platform_fclose(FILE *stream);
405
406 /*
407  * Function: platform_ferror
408  *  Tests for an error on a stream.
409  *
410  * Parameters:
411  *  stream - Pointer to stream.
412  *
413  * Returns:
414  *  If not error has occured on `stream`, 0 value is returned, otherwise
415  *  it returns a nonzero value.
416  *
417  * Remarks:
418  *  Tests for a reading or writing error on the file associated with `stream`.
419  *  If an error has occured, the error indicator for the stream remains set
420  *  until the stream is closed or rewound.
421  */
422 int platform_ferror(FILE *stream);
423
424 /*
425  * Function: platform_fgetc
426  *  Read a character from a stream.
427  *
428  * Parameters:
429  *  stream - Pointer to a stream.
430  *
431  * Returns:
432  *  The chracter read as an int or EOF to indicate an error or end-of-file.
433  *
434  * Remarks:
435  *  Reads a single chracter from the current position of the file associated
436  *  with `stream`. Than increments that position. If the steam is at the end
437  *  of the file, the end-of-file indicator for the stream is set.
438  */
439 int platform_fgetc(FILE *stream);
440
441 /*
442  * Function: platform_fputs
443  *  Write a string to a stream
444  *
445  * Parameters:
446  *  str    - Output string.
447  *  stream - Pointer to stream.
448  *
449  * Returns:
450  *  Non-negative value if successful. EOF is used to indicate an error.
451  *
452  * Remarks:
453  *  Copies `str` to the output stream at the current position.
454  */
455 int platform_fputs(const char *str, FILE *stream);
456
457 /*
458  * Function: platform_fseek
459  *  Moves the file pointer to a specified location.
460  *
461  * Parameters:
462  *  stream - Pointer to stream.
463  *  offset - Number of bytes from origin to offset.
464  *  origin - Initital position.
465  *
466  * Returns:
467  *  0 value, nonzero values are used to indicate an error.
468  *
469  * Remarks:
470  *  Moves the file pointer (if any) associated with stream to a new
471  *  location that is offset bytes from origin.
472  *  The next operation on the stream takes place at the new location.
473  *  On a stream open for update, the next operation can be either a
474  *  read or a write.
475  */
476 int platform_fseek(FILE *stream, long offset, int origin);
477
478 /*
479  * Function: platform_ftell
480  *  Gets the current position of a file pointer
481  *
482  * Parameters:
483  *  stream - Pointer to stream
484  *
485  * Returns:
486  *  Current file position. May not reflect physical byte offset, e.g
487  *  systems where read-mode does carriage return-linefeed translation.
488  *  -1 value is used to indivate an error.
489  */
490 long platform_ftell(FILE *stream);
491
492 /*
493  * Function: platform_mkdir
494  *  Make a directory
495  *
496  * Parameters:
497  *  path    - Path to create
498  *  mode    - The mode of the directory (implementation defined)
499  *
500  * Returns:
501  *  0 value. -1 value is used to indicate an error. On error no
502  *  directory shall be created.
503  *
504  * Remarks:
505  *  Shall create a new empty directory with with the name path specified
506  *  by argument `path.
507  */
508 int platform_mkdir(const char *path, int mode);
509
510 /*
511  * Function: platform_opendir
512  *  Open a directory
513  *
514  * Parameters:
515  *  path - Path to the directory to open
516  *
517  * Returns:
518  *  Pointer to an object of type *DIR*. A null pointer value indicates
519  *  an error.
520  *
521  * Remarks:
522  *  Shall open a directory stream corresponding to the directory named by
523  *  the `path` argument. The directory stream is positioned at the first entry.
524  */
525 DIR *platform_opendir(const char *path);
526
527 /*
528  * Function: platform_closedir
529  *  Close a directory stream
530  *
531  * Parameters:
532  *  dir - Pointer to directory stream
533  *
534  * Returns:
535  *  0 value. A -1 value indicated an error.
536  *
537  * Remarks:
538  *  Shall close the directory stream referred to by the argument
539  *  `dir`. Upon return, the value of `dir` may no longer point to
540  *  an accessible object of the type *DIR*.
541  */
542 int platform_closedir(DIR *dir);
543
544 /*
545  * Function: platform_readdir
546  *  Read directory
547  *
548  * Parameters:
549  *  dir - Pointer to directory stream
550  *
551  * Returns:
552  *  Pointer to an object of type `struct dirent`. A null pointer value
553  *  indicates an error.
554  *
555  * Remarks:
556  *  When the end of the directory is encountered, a null pointer is
557  *  returned.
558  */
559 struct dirent *platform_readdir(DIR *dir);
560
561 /*
562  * Function: platform_isatty
563  *  Determines whether a file descriptor is associated with a character
564  *  device.
565  *
566  * Returns:
567  *  A nonzero value if the descriptor is associated with a character
568  *  device. Otherwise `platform_isatty` returns 0.
569  */
570 int platform_isatty(int fd);
571
572 #endif