amxmodx/plugins/include/file.inc
Arkshine 52c73126e1 VFS: Fix various things
- The "ALL" fake pathID is replaced by what does SM, having a public var NULL_STRING which will acts as NULL when needed.
  To make compiler accepting public array, this patch was needed: https://hg.alliedmods.net/sourcemod-central/rev/b12f329def09
- The offset thing in read_dir: considering that's something very specific to this native and that implementation in CDirectory doesn't make sense because of the offset compatibility for windows, all code is now in the native.
2015-03-25 13:50:07 +01:00

667 lines
23 KiB
SourcePawn
Executable File

// vim: set ts=4 sw=4 tw=99 noet:
//
// AMX Mod X, based on AMX Mod by Aleksander Naszko ("OLO").
// Copyright (C) The AMX Mod X Development Team.
//
// This software is licensed under the GNU General Public License, version 3 or higher.
// Additional exceptions apply. For full license details, see LICENSE.txt or visit:
// https://alliedmods.net/amxmodx-license
//
// File Functions
//
#if defined _file_included
#endinput
#endif
#define _file_included
/**
* @note All paths in AMX Mod X natives are relative to the mod folder
* unless otherwise noted.
*
* Most functions in AMX Mod X (at least, ones that deal with direct
* file manipulation) will support an alternate path specification.
*/
/**
* Maximum path length.
*/
#define PLATFORM_MAX_PATH 256
/**
* File inode types for use with open_dir() and next_file().
*/
enum FileType
{
FileType_Unknown, /* Unknown file type (device/socket) */
FileType_Directory, /* File is a directory */
FileType_File, /* File is a file */
};
/**
* File time modes for use with GetFileTime().
*/
enum FileTimeType
{
FileTime_LastAccess, /* Last access (not available on FAT) */
FileTime_Created, /* Creation (not available on FAT) */
FileTime_LastChange, /* Last modification */
};
/**
* File position modes for use with fseek().
*/
#define SEEK_SET 0 /* Seek from start */
#define SEEK_CUR 1 /* Seek from current position */
#define SEEK_END 2 /* Seek from end position */
/**
* Options for use with file_size() flag parameter.
*/
#define FSOPT_BYTES_COUNT 0 /* Returns the file size in number of bytes */
#define FSOPT_LINES_COUNT 1 /* Returns how many lines there are in this file */
#define FSOPT_END_WITH_LF 2 /* Returns whether the last line is '\n' */
/**
* Data block modes for use with fread*() and fwrite*().
*/
#define BLOCK_INT 4
#define BLOCK_SHORT 2
#define BLOCK_CHAR 1
#define BLOCK_BYTE 1
/**
* File permissions flags for use with mkdir() and SetFilePermissions().
*/
#define FPERM_U_READ 0x0100 /* User can read. */
#define FPERM_U_WRITE 0x0080 /* User can write. */
#define FPERM_U_EXEC 0x0040 /* User can exec. */
#define FPERM_U_RWX FPERM_U_READ | FPERM_U_WRITE | FPERM_U_EXEC
#define FPERM_G_READ 0x0020 /* Group can read. */
#define FPERM_G_WRITE 0x0010 /* Group can write. */
#define FPERM_G_EXEC 0x0008 /* Group can exec. */
#define FPERM_G_RWX FPERM_G_READ | FPERM_G_WRITE | FPERM_G_EXEC
#define FPERM_O_READ 0x0004 /* Anyone can read. */
#define FPERM_O_WRITE 0x0002 /* Anyone can write. */
#define FPERM_O_EXEC 0x0001 /* Anyone can exec. */
#define FPERM_O_RWX FPERM_O_READ | FPERM_O_WRITE | FPERM_O_EXEC
#define FPERM_DIR_DEFAULT FPERM_U_RWX | FPERM_G_RWX | FPERM_O_RWX /* rwx r-x r-x (0755) */
/**
* Reads content from directory
*
* @note This native is expensive. Consider the use of open_dir(), next_file() and close_dir() instead.
* @note Both the '.' and '..' automatic directory entries will be retrieved for Windows and Linux.
*
* @param dirname Path to open
* @param pos Index the element
* @param output String buffer to hold content
* @param len Maximum size of string buffer
* @param outlen Number of characters written to the buffer
*
* @return Returns index of next element, otherwiwe 0 when end of dir is reached
*/
native read_dir(const dirname[], pos, output[], len, &outlen = 0);
/**
* Reads line from file.
*
* @note This native is expensive. Consider the use of new file natives (fopen(), fgets(), etc.)
* if purpose is to read several lines of a file.
*
* @param file Path to open
* @param line Index of the line, starting to 0
* @param text String buffer to hold line read
* @param len Maximum size of string buffer
* @param txtlen Number of characters written to the buffer
*
* @return Returns index of next line, otherwise 0 when end of file is reached
* @error Unable to read the file
*/
native read_file(const file[], line, text[], len, &txtlen = 0);
/**
* Writes text to file.
*
* @note This native is expensive. Consider the use of new file natives (fopen(), fputs(), etc.)
* if purpose is to write several lines of a file.
*
* @param file Path to open
* @param text String to write to
* @param line Index of the line, starting to 0
* If < 0, content will be appended
*
* @noreturn
* @error Unable to write [temporary] file
*/
native write_file(const file[], const text[], line = -1);
/**
* Deletes a file.
*
* @param file Path of the file to delete
* @param use_valve_fs If true, the Valve file system will be used instead.
* This can be used to delete files existing in the Valve
* search path, rather than solely files existing directly
* in the gamedir.
* @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for all search paths.
*
* @return 1 on success, 0 on failure or if file not immediately removed.
*/
native delete_file(const file[], bool:use_valve_fs = false, const valve_path_id[] = "GAMECONFIG");
/**
* Checks if a file exists.
*
* @param file Path to the file
* @param use_valve_fs If true, the Valve file system will be used instead.
* This can be used to find files existing in any of
* the Valve search paths, rather than solely files
* existing directly in the gamedir.
*
* @return 1 if the file exists, 0 otherwise
*/
native file_exists(const file[], bool:use_valve_fs = false);
/**
* Renames a file.
*
* @param oldname New path to the file
* @param newname Path to the existing file
* @param relative If true, native will act like other natives which
* use the moddir as a base directory. Otherwise, the
* current directory is undefined (but assumed to be hlds).
*
* @return 1 on success, 0 otherwise
*/
native rename_file(const oldname[], const newname[], relative = 0);
/**
* Checks if a directory exists.
*
* @param dir Path to the directory
* @param use_valve_fs If true, the Valve file system will be used instead.
* This can be used to find files existing in any of
* the Valve search paths, rather than solely files
* existing directly in the gamedir.
*
* @return 1 if the directory exists, 0 otherwise
*/
native dir_exists(const dir[], bool:use_valve_fs = false);
/**
* Get the file size in bytes.
*
* @param file Path to the file
* @param flag Flag options, see FSOPT_* constants
* @param use_valve_fs If true, the Valve file system will be used instead.
* This can be used to find files existing in any of
* the Valve search paths, rather than solely files
* existing directly in the gamedir.
* If used, flag option is ignored.
* @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for all search paths
*
* @return If flag is FSOPT_BYTES_COUNT or use_valve_fs to true, the file size in bytes
* If flag is FSOPT_LINES_COUNT, the number of lines in the file
* If flag is FSOPT_END_WITH_LF, 1 is returned if file ends with line feed
* If file doesn't exist, -1
*/
native file_size(const file[], flag = FSOPT_BYTES_COUNT, bool:use_valve_fs = false, const valve_path_id[] = "GAME");
/**
* Opens or creates a file, returning a file handle on success. File handles
* should be closed with fclose().
*
* @note The open mode may be one of the following strings:
* "r": Open an existing file for reading.
* "w": Create a file for writing, or truncate (delete the contents of) an
* existing file and then open it for writing.
* "a": Create a file for writing, or open an existing file such that writes
* will be appended to the end.
* "r+": Open an existing file for both reading and writing.
* "w+": Create a file for reading and writing, or truncate an existing file
* and then open it for reading and writing.
* "a+": Create a file for both reading and writing, or open an existing file
* such that writes will be appended to the end.
*
* @note The open mode may also contain an additional character after "r", "w", or "a",
* but before any "+" sign. This character may be "b" (indicating binary mode) or
* "t" (indicating text mode). By default, "text" mode is implied. On Linux and
* Mac, this has no distinction from binary mode. On Windows, it causes the '\n'
* character (0xA) to be written as "\r\n" (0xD, 0xA).
*
* Example: "rb" opens a binary file for writing; "at" opens a text file for
* appending.
*
* @note Registered paths ID are (in priority order) :
* GAME All paths related to current mod, including fallback
* Depending settings, it includes: <gamedir>_lv/_addon/_<language>/_hd
* and <gamedir> itself
* GAMECONFIG The default writable directory (<gamedir>)
* GAMEDOWNLOAD The download directory (<gamedir>_download)
* GAME_FALLBACK All paths related to fallback game, same as GAME
* DEFAULTGAME All paths related to the default game which is "valve", same as GAME
* BASE The base path where server is installed
*
* Note that some paths are non-writable. It includes all <gamedir>_* (expect _download)
* and DEFAULTGAME. Any file inside a non-writable path will be ignored if you try to open
* it in writing mode.
*
* @param filename File to open
* @param mode Open mode
* @param use_valve_fs If true, the Valve file system will be used instead
* This can be used to finred files existing in valve
* search paths, rather than solely files existing directly
* in the gamedir.
* @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for all search paths
*
* @return A file handle, or null if the file could not be opened.
*/
native fopen(const filename[], const mode[], bool:use_valve_fs = false, const valve_path_id[] = "GAME");
/**
* Closes a file handle.
*
* @param file File handle
*/
native fclose(file);
/**
* Reads a single binary data from a file.
*
* @param file Handle to the file
* @param data Variable to store item read
* @param mode Size of each element, in bytes, to be read
* See BLOCK_* constants
*
* @return Number of elements read
*/
native fread(file, &any:data, mode);
/**
* Reads binary data from a file.
*
* @param file Handle to the file
* @param data Array to store each item read
* @param blocks Number of items to read into the array
* @param mode Size of each element, in bytes, to be read
* Valid sizes are 1, 2, or 4. See BLOCK_* constants.
*
* @return Number of elements read
*/
native fread_blocks(file, any:data[], blocks, mode);
/**
* Reads raw binary data from a file.
*
* @param file Handle to the file
* @param stream Array to store each item read
* @param blocksize Number of items to read into the array
* @param blocks Size of each element, in bytes. The data is read directly.
* That is, in 1 or 2-byte mode, the lower byte(s) in
* each cell are used directly, rather than performing
* any casts from a 4-byte number to a smaller number.
*
* @return Number of elements read
*/
native fread_raw(file, any:stream[], blocksize, blocks);
/**
* Writes a single binary data to a file.
*
* @param file Handle to the file
* @param data Item to write
* @param mode Size of each item in the array in bytes
* Valid sizes are 1, 2, or 4. See BLOCK_* constants
*
* @return Number of elements written
*/
native fwrite(file, any:data, mode);
/**
* Writes binary data to a file.
*
* @param file Handle to the file
* @param data Array of items to write
* @param blocks Number of items in the array
* @param mode Size of each item in the array in bytes
* Valid sizes are 1, 2, or 4. See BLOCK_* constants
*
* @return Number of elements written
*/
native fwrite_blocks(file, const any:data[], blocks, mode);
/**
* Writes raw binary data to a file.
*
* @param file Handle to the file.
* @param stream Array of items to write. The data is written directly.
* That is, in 1 or 2-byte mode, the lower byte(s) in
* each cell are used directly, rather than performing
* any casts from a 4-byte number to a smaller number.
* @param blocks Size of each item in the array in bytes.
* @param mode Number of items in the array.
*
* @return Number of elements written
*/
native fwrite_raw(file, const any:stream[], blocks, mode);
/**
* Tests if the end of file has been reached.
*
* @param file Handle to the file
*
* @return 1 if end of file has been reached, 0 otherwise.
*/
native feof(file);
/**
* Reads a line from a text file.
*
* @param file Handle to the file.
* @param buffer String buffer to hold the line
* @param maxlength Maximum size of string buffer
*
* @return Total number of characters written on success, 0 otherwise
*/
native fgets(file, buffer[], maxlength);
/**
* Writes a line of text to a text file.
*
* @param file Handle to the file
* @param text String to write
* @param null_term True to append NULL terminator, false otherwise
*
* @return 0 on success, -1 otherwise
*/
native fputs(file, const text[], bool:null_term = false);
/**
* Writes a line of formatted text to a text file.
*
* @param file Handle to the file
* @param format Formatting rules
* @param ... Variable number of format parameters
*
* @return Total number of characters written on success, 0 otherwise
*/
native fprintf(file, const fmt[], any:...);
/**
* Sets the file position indicator.
*
* @param file Handle to the file
* @param position Position relative to what is specified in whence
* @param start SEEK_ constant value of where to see from
*
* @return 0 on success, a non-zero value otherwise
*/
native fseek(file, position, start);
/**
* Gets current position in the file.
*
* @param file Handle to the file
*
* @return Value for the file position indicator
*/
native ftell(file);
/**
* Gets character from file.
*
* @param file Handle to the file
*
* @return Character read on success, -1 otherwise
*/
native fgetc(file);
/**
* Writes character to file
*
* @param file Handle to the file
* @param data Character to put
*
* @return Character written on success, -1 otherwise
*/
native fputc(file, data);
/**
* Ungets character from file.
*
* @param file Handle to the file
* @param data Character to unget
*
* @return On success, the character put back is returned, -1 otherwise
*/
native fungetc(file, data);
/**
* Flushes a buffered output stream.
*
* @param file File handle, or 0 for all open streams
*
* @return 0 on success, -1 on failure
*/
native fflush(file);
/**
* Gets the formatted file size in bytes.
*
* @param filename Path to the file
* @param ... Variable number of format parameters
*
* @return File size in bytes, otherwise -1 if file not found
*/
native filesize(const filename[], any:...);
/**
* Removes a directory.
*
* @note On most Operating Systems you cannot remove a directory which has files inside it.
*
* @param path Path to the directory
*
* @return 1 on success, 0 otherwise
*/
native rmdir(const path[]);
/**
* Creates a directory.
*
* @param path Path to create
* @param mode Permissions (default is o=rx,g=rx,u=rwx). Note that folders must have
* the execute bit set on Linux. On Windows, the mode is ignored.
* @param use_valve_fs If true, the Valve file system will be used instead
* This can be used to create folders in the game's
* Valve search paths, rather than directly in the gamedir.
* @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for default
* In this case, mode is ignored
*
* @return 0 on success, -1 otherwise
*/
native mkdir(const dirname[], mode = FPERM_DIR_DEFAULT, bool:use_valve_fs = false, const valve_path_id[] = "GAMECONFIG");
/**
* Deletes a file (delete_file macro)
*
* @param filename Path of the file to delete
* @param use_valve_fs If true, the Valve file system will be used instead.
* This can be used to delete files existing in the Valve
* search path, rather than solely files existing directly
* in the gamedir.
* @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for all search paths
*
* @return 1 on success, 0 on failure or if file not immediately removed
*/
native unlink(const filename[], bool:use_valve_fs = false, const valve_path_id[] = "GAMECONFIG");
/**
* Opens a directory/folder for contents enumeration.
*
* @note Directories are closed with close_dir().
*
* @param dir Path to open.
* @param firstfile String buffer to hold first file name
* @param length Maximum size of the string buffer
* @param type Optional variable to store the file type
* @param use_valve_fs If true, the Valve file system will be used instead.
* This can be used to find files existing in any of
* the Valve search paths, rather than solely files
* existing directly in the gamedir.
* @param valve_path_id If use_valve_fs, a search path from gameinfo or NULL_STRING for all search paths.
*
* @return Handle to the directory, 0 otherwise
*/
native open_dir(dir[], firstfile[], length, &FileType:type = FileType_Unknown, bool:use_valve_fs = false, const valve_path_id[] = "GAME");
/**
* Reads the next directory entry as a local filename.
*
* @note Contents of buffers are undefined when returning false.
* @note Both the '.' and '..' automatic directory entries will be retrieved for Windows and Linux.
*
* @param dirh Handle to a directory
* @param buffer String buffer to hold directory name
* @param length Maximum size of string buffer
* @param type Optional variable to store the file type. FileType_* constants
*
* @return 1 on success, 0 if there are no more files to read.
*/
native next_file(dirh, buffer[], length, &FileType:type = FileType_Unknown);
/**
* Closes the directory.
*
* @param dirh Handle to a directory
*/
native close_dir(dirh);
/**
* Loads a file using the LoadFileForMe engine function.
*
* The data is truncated if there is not enough space. No null-terminator
* is applied; the data is the raw contents of the file.
*
* @param file File to load (may be a file from the GCF)
* @param buffer Buffer to store file contents
* @param maxlength Maximum size of the file buffer
* @param length Variable to store the file length. This may return
* a number larger than the buffer size
* @return -1 if the file could not be loaded. Otherwise,
* the number of cells actually written to the buffer
* are returned.
*/
native LoadFileForMe(const file[], buffer[], maxlength, &length = 0);
/**
* Returns a file timestamp as a unix timestamp.
*
* @param file File name
* @param tmode Time mode, see FileTime_* constants
*
* @return Returns a file timestamp as a unix timestamp
*/
native GetFileTime(const file[], FileTimeType:tmode);
/**
* Changes a file or directories permissions.
*
* @param path Path to the file
* @param mode Permissions to set, see FPERM_* constants
*
* @return True on success, false otherwise
*/
native bool:SetFilePermissions(const path[], mode);
/**
* Reads a single int8 (byte) from a file. The returned value is sign-
* extended to an int32.
*
* @param file Handle to the file
* @param data Variable to store the data read
*
* @return True on success, false on failure
*/
native bool:FileReadInt8(file, &any:data);
/**
* Reads a single uint8 (unsigned byte) from a file. The returned value is
* zero-extended to an int32.
*
* @param file Handle to the file
* @param data Variable to store the data read
*
* @return True on success, false on failure
*/
native bool:FileReadUint8(file, &any:data);
/**
* Reads a single int16 (short) from a file. The value is sign-extended to
* an int32.
*
* @param file Handle to the file
* @param data Variable to store the data read
*
* @return True on success, false on failure
*/
native bool:FileReadInt16(file, &any:data);
/**
* Reads a single unt16 (unsigned short) from a file. The value is zero-
* extended to an int32.
*
* @param file Handle to the file
* @param data Variable to store the data read
*
* @return True on success, false on failure
*/
native bool:FileReadUint16(file, &any:data);
/**
* Reads a single int32 (int/cell) from a file.
*
* @param file Handle to the file
* @param data Variable to store the data read
*
* @return True on success, false on failure
*/
native bool:FileReadInt32(file, &any:data);
/**
* Writes a single int8 (byte) to a file.
*
* @param file Handle to the file
* @param data Data to write (truncated to an int8)
*
* @return True on success, false on failure
*/
native bool:FileWriteInt8(file, any:data);
/**
* Writes a single int16 (short) to a file.
*
* @param file Handle to the file
* @param data Data to write (truncated to an int16)
*
* @return True on success, false on failure
*/
native bool:FileWriteInt16(file, any:data);
/**
* Writes a single int32 (int/cell) to a file.
*
* @param file Handle to the file
* @param data Data to write
*
* @return True on success, false on failure
*/
native bool:FileWriteInt32(file, any:data);