X-Git-Url: https://git.xonotic.org/?a=blobdiff_plain;f=platform.h;h=57ba3526b4fbef9ce695f703c9fada81b76e3d19;hb=783b7b6594cb3fde2b9bf945df7a68cb3afa2d5f;hp=f73152a09d8f83d62a39e0e7b3a9f9c2b0cd366d;hpb=4d0bf1607a8105201190233c60556d1f8b307f21;p=xonotic%2Fgmqcc.git diff --git a/platform.h b/platform.h index f73152a..57ba352 100644 --- a/platform.h +++ b/platform.h @@ -1,5 +1,5 @@ /* - * Copyright (C) 2012, 2013 + * Copyright (C) 2012, 2013, 2014, 2015 * Dale Weiler * * Permission is hereby granted, free of charge, to any person obtaining a copy of @@ -60,14 +60,13 @@ int dd_stat; char dd_name[1]; } DIR; - -# ifdef S_ISDIR -# undef S_ISDIR -# endif /*! S_ISDIR */ -# define S_ISDIR(X) ((X)&_S_IFDIR) # else # include # endif /*!__MINGW32__*/ + +# ifndef S_ISDIR +# define S_ISDIR(X) ((X)&_S_IFDIR) +# endif #else # include # include @@ -186,24 +185,6 @@ const char *platform_ctime(const time_t *timer); */ char *platform_strncat(char *dest, const char *src, size_t num); -/* - * Function: platform_tmpnam - * Generates names you can use to create temporary files. - * - * Parameters: - * str - Pointer that will hold the generated name and will be identical - * to the name returned by the function. This is a convenient way - * to save the generated name. - * - * Returns: - * Pointer to the name generate or *NULL* if there is a failure. Failure - * can occur if you attempt more than TMP_MAX calls. - * - * Remarks: - * Returns a name unique in the current workign directory. - */ -const char *platform_tmpnam(char *str); - /* * Function: platform_getenv * Get a value from the current enviroment. @@ -217,10 +198,47 @@ const char *platform_tmpnam(char *str); * pointer. The return value is *NULL* if `var` is not found in the * enviroment table. */ -const char *platform_getenv(char *var); +const char *platform_getenv(const char *var); +/* + * Function: platform_vasprintf + * Print to allocated string + * + * Parameters: + * dat - Pointer to pointer to store allocated data. + * fmt - Format specification. + * args - Variable argument list. + * + * Returns: + * Number of character written, -1 is used to indicate an error. + * + * Remarks: + * Allocate a string large enough to hold the output including + * the terminating null character than write formatted output + * to it using format specification. + */ int platform_vasprintf(char **dat, const char *fmt, va_list args); +/* + * Function: platform_vfprintf + * Write formatted output using a pointer to a list of arguments. + * + * Parameters: + * stream - Pointer to stream. + * format - Format specification. + * atrg - Variable argument list. + * + * Returns: + * Number of characters written, not including the terminating null + * character, or a negitive value if an output error occurs. -1 is + * also used to indicate an error. + * + * Remarks: + * Takes a pointer to an argument list, then formats and writes the + * given data to `stream`. + */ +int platform_vfprintf(FILE *stream, const char *format, va_list arg); + /* * Function: platform_strcat * Append characters of a string. @@ -288,20 +306,238 @@ const char *platform_strerror(int err); */ FILE *platform_fopen(const char *filename, const char *mode); +/* + * Function: platform_fread + * Reads data from a stream + * + * Parameters: + * ptr - Storage location for data. + * size - Item size in bytes. + * count - Maximum number of items to be read. + * stream - Pointer to stream + * + * Returns: + * The number of full items actually read, which may be less than `count` + * if an error occurs or if the end of the file is encountered before + * reaching `count`. If `size` or `count` is 0, `platform_fread` + * returns 0 and the buffer contents are unchanged. + */ size_t platform_fread(void *ptr, size_t size, size_t count, FILE *stream); + +/* + * Function: platform_fwrite + * Writes data to a stream + * + * Parameters: + * ptr - Pointer to data to be written. + * size - Item size in bytes. + * count - Maximum number of items to be read. + * stream - Pointer to stream + * + * Returns: + * The number of full items actually written, which may be less than + * `count` if an error occurs. Also, if an error occurs, the + * file-position indicator cannot be determined. + * + * Remarks: + * Writes up to `count` items, of `size` length each, from `ptr` to the + * output stream. The file pointer associated with stream (if there is one) + * is incremented by the number of bytes actually written. + */ size_t platform_fwrite(const void *ptr, size_t size, size_t count, FILE *stream); + +/* + * Function: platform_fflush + * Flushes a stream + * + * Parameters: + * stream - Pointer to stream + * + * Returns: + * 0 value if the buffer was succesffuly flushed. The value 0 is also + * returned in cases in which the specified stream has no buffer or is + * open for reading only. A return value of *EOF* indicates an error. + * + * Remarks: + * Flushes a stream. If the file associated with stream is open for output, + * platform_fflush writes to that file the contents of the buffer + * associated with the stream. If the stream is open for input, + * platform_fflush clears the contents of the buffer. platform_fflush + * negates the effect of any prior call to ungetc against stream. Also, + * platform_fflush(NULL) flushes all streams opened for output. + * The stream remains open after the call. platform_fflush has no effect + * on an unbuffered stream. + */ int platform_fflush(FILE *stream); -int platform_vfprintf(FILE *stream, const char *format, va_list arg); + +/* + * Function: platform_fclose + * Closes a stream. + * + * Parameters: + * stream - Pointer to stream. + * + * Returns: + * 0 value. *EOF* is used to indicate an error. + * + * Remarks: + * Closes a stream. + */ int platform_fclose(FILE *stream); + +/* + * Function: platform_ferror + * Tests for an error on a stream. + * + * Parameters: + * stream - Pointer to stream. + * + * Returns: + * If not error has occured on `stream`, 0 value is returned, otherwise + * it returns a nonzero value. + * + * Remarks: + * Tests for a reading or writing error on the file associated with `stream`. + * If an error has occured, the error indicator for the stream remains set + * until the stream is closed or rewound. + */ int platform_ferror(FILE *stream); + +/* + * Function: platform_fgetc + * Read a character from a stream. + * + * Parameters: + * stream - Pointer to a stream. + * + * Returns: + * The chracter read as an int or EOF to indicate an error or end-of-file. + * + * Remarks: + * Reads a single chracter from the current position of the file associated + * with `stream`. Than increments that position. If the steam is at the end + * of the file, the end-of-file indicator for the stream is set. + */ int platform_fgetc(FILE *stream); + +/* + * Function: platform_fputs + * Write a string to a stream + * + * Parameters: + * str - Output string. + * stream - Pointer to stream. + * + * Returns: + * Non-negative value if successful. EOF is used to indicate an error. + * + * Remarks: + * Copies `str` to the output stream at the current position. + */ int platform_fputs(const char *str, FILE *stream); + +/* + * Function: platform_fseek + * Moves the file pointer to a specified location. + * + * Parameters: + * stream - Pointer to stream. + * offset - Number of bytes from origin to offset. + * origin - Initital position. + * + * Returns: + * 0 value, nonzero values are used to indicate an error. + * + * Remarks: + * Moves the file pointer (if any) associated with stream to a new + * location that is offset bytes from origin. + * The next operation on the stream takes place at the new location. + * On a stream open for update, the next operation can be either a + * read or a write. + */ int platform_fseek(FILE *stream, long offset, int origin); + +/* + * Function: platform_ftell + * Gets the current position of a file pointer + * + * Parameters: + * stream - Pointer to stream + * + * Returns: + * Current file position. May not reflect physical byte offset, e.g + * systems where read-mode does carriage return-linefeed translation. + * -1 value is used to indivate an error. + */ long platform_ftell(FILE *stream); +/* + * Function: platform_mkdir + * Make a directory + * + * Parameters: + * path - Path to create + * mode - The mode of the directory (implementation defined) + * + * Returns: + * 0 value. -1 value is used to indicate an error. On error no + * directory shall be created. + * + * Remarks: + * Shall create a new empty directory with with the name path specified + * by argument `path. + */ int platform_mkdir(const char *path, int mode); + +/* + * Function: platform_opendir + * Open a directory + * + * Parameters: + * path - Path to the directory to open + * + * Returns: + * Pointer to an object of type *DIR*. A null pointer value indicates + * an error. + * + * Remarks: + * Shall open a directory stream corresponding to the directory named by + * the `path` argument. The directory stream is positioned at the first entry. + */ DIR *platform_opendir(const char *path); + +/* + * Function: platform_closedir + * Close a directory stream + * + * Parameters: + * dir - Pointer to directory stream + * + * Returns: + * 0 value. A -1 value indicated an error. + * + * Remarks: + * Shall close the directory stream referred to by the argument + * `dir`. Upon return, the value of `dir` may no longer point to + * an accessible object of the type *DIR*. + */ int platform_closedir(DIR *dir); + +/* + * Function: platform_readdir + * Read directory + * + * Parameters: + * dir - Pointer to directory stream + * + * Returns: + * Pointer to an object of type `struct dirent`. A null pointer value + * indicates an error. + * + * Remarks: + * When the end of the directory is encountered, a null pointer is + * returned. + */ struct dirent *platform_readdir(DIR *dir); /*