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