f73152a09d8f83d62a39e0e7b3a9f9c2b0cd366d
[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
64 #       ifdef S_ISDIR
65 #           undef  S_ISDIR
66 #       endif /*! S_ISDIR */
67 #       define S_ISDIR(X) ((X)&_S_IFDIR)
68 #   else
69 #       include <dirent.h>
70 #   endif /*!__MINGW32__*/
71 #else
72 #   include <sys/types.h>
73 #   include <sys/stat.h>
74 #   include <unistd.h>
75 #   include <dirent.h>
76 #endif /*!_WIN32*/
77
78 /*
79  * Function: platform_vsnprintf
80  *  Write formatted output using a pointer to a lis of arguments.
81  *
82  * Parameters:
83  *  buffer - Storage location for output.
84  *  bytes  - Maximum number of characters to write.
85  *  format - Format specification.
86  *  arg    - Variable argument list.
87  *
88  * Returns:
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.
94  *
95  * Remarks:
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.
100  */
101 int platform_vsnprintf(char *buffer, size_t bytes, const char *format, va_list arg);
102
103 /*
104  * Function: platform_vsscanf
105  *  Reads formatted data from a string.
106  *
107  * Parameters:
108  *  buffer - Stored data to read.
109  *  format - Format specification.
110  *  arg    - Variable argument list.
111  *
112  * Returns:
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.
118  *
119  * Remarks:
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.
127  */
128 int platform_vsscanf(const char *buffer, const char *format, va_list arg);
129
130 /*
131  * Function: platform_localtime
132  *  Convert a time value and correct for the local time zone.
133  *
134  * Parameters
135  *  timer - Pointer to stored time.
136  *
137  * Returns:
138  *  A pointer to a structure result, or NULL if the date passed to
139  *  the function is before midnight, January 1, 1970.
140  */
141 const struct tm *platform_localtime(const time_t *timer);
142
143 /*
144  * Function: platform_ctime
145  *  Convert a time value to a string and adjust for local time zone
146  *  settings.
147  *
148  * Parameters:
149  *  timer - Pointer to stored time.
150  *
151  * Returns:
152  *  Pointer to the character string result. NULL will be returned if time
153  *  represents a date before midnight, January 1, 1970, UTC.
154  *
155  * Remarks:
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.
163  */
164 const char *platform_ctime(const time_t *timer);
165
166 /*
167  * Function: platform_strncat
168  *  Append characters of a string.
169  *
170  * Parameters:
171  *  dest - Null terminated destination string
172  *  src  - Source string
173  *  num  - Number of characters to append
174  *
175  * Returns:
176  *  Pointer to the destination string. No return value is used to indicate
177  *  an error.
178  *
179  * Remarks:
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`.
186  */
187 char *platform_strncat(char *dest, const char *src, size_t num);
188
189 /*
190  * Function: platform_tmpnam
191  *  Generates names you can use to create temporary files.
192  *
193  * Parameters:
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.
197  *
198  * Returns:
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.
201  *
202  * Remarks:
203  *  Returns a name unique in the current workign directory.
204  */
205 const char *platform_tmpnam(char *str);
206
207 /*
208  * Function: platform_getenv
209  *  Get a value from the current enviroment.
210  *
211  * Parameters:
212  *  var - Enviroment variable name
213  *
214  * Returns:
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
218  *  enviroment table.
219  */
220 const char *platform_getenv(char *var);
221
222 int platform_vasprintf(char **dat, const char *fmt, va_list args);
223
224 /*
225  * Function: platform_strcat
226  *  Append characters of a string.
227  *
228  * Parameters:
229  *  dest - Null terminated destination string
230  *  src  - Source string
231  *
232  * Returns:
233  *  Pointer to the destination string. No return value is used to indicate
234  *  an error.
235  *
236  * Remarks:
237  *  Appens `src` to `dest` and terminates with resulting null character.
238  *  The initial character of `src` overwrites the terminating null
239  *  character of `dest`. The behaviour of platform_strcat is undefined
240  *  if the source and destination string overlap.
241  */
242 char *platform_strcat(char *dest, const char *src);
243
244 /*
245  * Function: platform_strncpy
246  *  Copys characters of one string to another.
247  *
248  * Parameters:
249  *  dest - Destination string.
250  *  src  - Source string.
251  *  num  - Number of characters to be copied.
252  *
253  * Returns:
254  *  `dest`. No return value is reserved to indicate an error.
255  *
256  * Remarks:
257  *  Copies the initial characters of `src` to `dest` and returns `dest`.
258  *  If `num` is less than or equal to the length of `src1 a null character
259  *  is not appended automatically to the copied string. If `num` is greater
260  *  than the length of `src`, the destination string is padded with null
261  *  characters up to length `num`. The behaviour of this function is undefined
262  *  if the source and destination strings overlap.
263  */
264 char *platform_strncpy(char *dest, const char *src, size_t num);
265
266 /*
267  * Function: platform_strerror
268  *  Get a system error message
269  *
270  * Parameters:
271  *  err - Error number.
272  *
273  * Returns:
274  *  A pointer to the error message
275  */
276 const char *platform_strerror(int err);
277
278 /*
279  * Function: platform_fopen
280  *  Opens a file
281  *
282  * Parameters:
283  *  filename - File name.
284  *  mode     - Kind of access that's enabled.
285  *
286  * Returns:
287  *  A pointer to the open file. A null pointer value indicates an error.
288  */
289 FILE *platform_fopen(const char *filename, const char *mode);
290
291 size_t platform_fread(void *ptr, size_t size, size_t count, FILE *stream);
292 size_t platform_fwrite(const void *ptr, size_t size, size_t count, FILE *stream);
293 int platform_fflush(FILE *stream);
294 int platform_vfprintf(FILE *stream, const char *format, va_list arg);
295 int platform_fclose(FILE *stream);
296 int platform_ferror(FILE *stream);
297 int platform_fgetc(FILE *stream);
298 int platform_fputs(const char *str, FILE *stream);
299 int platform_fseek(FILE *stream, long offset, int origin);
300 long platform_ftell(FILE *stream);
301
302 int platform_mkdir(const char *path, int mode);
303 DIR *platform_opendir(const char *path);
304 int platform_closedir(DIR *dir);
305 struct dirent *platform_readdir(DIR *dir);
306
307 /*
308  * Function: platform_isatty
309  *  Determines whether a file descriptor is associated with a character
310  *  device.
311  *
312  * Returns:
313  *  A nonzero value if the descriptor is associated with a character
314  *  device. Otherwise `platform_isatty` returns 0.
315  */
316 int platform_isatty(int fd);
317
318 #endif