Angband
Typedefs | Enumerations | Functions | Variables
z-file.h File Reference

Low-level file (and directory) handling. More...

#include "h-basic.h"

Go to the source code of this file.

Typedefs

typedef struct ang_file ang_file
 

File access code

More...
 
typedef struct ang_dir ang_dir
 An opaque file handle for Angband directory handling. More...
 

Enumerations

enum  file_mode { MODE_WRITE, MODE_READ, MODE_APPEND }
 Specifies what kind of access is required to a file. More...
 
enum  file_type { FTYPE_TEXT = 1, FTYPE_SAVE, FTYPE_RAW, FTYPE_HTML }
 Specifies what kind of thing a file is, when writing. More...
 

Functions

void safe_setuid_grab (void)
 Drop or grab privileges. More...
 
void safe_setuid_drop (void)
 Drop permissions. More...
 
size_t path_build (char *buf, size_t len, const char *base, const char *leaf)
 

Path building code

More...
 
size_t path_filename_index (const char *path)
 Return the index of the filename in a path, using PATH_SEPC. More...
 
bool file_exists (const char *fname)
 Utility functions. More...
 
bool file_delete (const char *fname)
 Tries to delete fname. More...
 
bool file_move (const char *fname, const char *newname)
 Moves the file fname to newname. More...
 
bool file_newer (const char *first, const char *second)
 Returns true if the file first is newer than second. More...
 
ang_filefile_open (const char *buf, file_mode mode, file_type ftype)
 File handle creation. More...
 
bool file_close (ang_file *f)
 Attempt to close the file handle f. More...
 
void file_lock (ang_file *f)
 File locking. More...
 
void file_unlock (ang_file *f)
 Unlock a file locked using file_lock(). More...
 
bool file_getl (ang_file *f, char *buf, size_t n)
 Line-based IO. More...
 
bool file_put (ang_file *f, const char *buf)
 Write the string pointed to by buf to the file represented by f. More...
 
bool file_putf (ang_file *f, const char *fmt,...)
 Format (using strnfmt) the given args, and then call file_put(). More...
 
bool file_vputf (ang_file *f, const char *fmt, va_list vp)
 Append a formatted line of text to the end of file 'f'. More...
 
bool file_skip (ang_file *f, int bytes)
 Byte-based IO. More...
 
int file_read (ang_file *f, char *buf, size_t n)
 Reads n bytes from file 'f' into buffer 'buf'. More...
 
bool file_write (ang_file *f, const char *buf, size_t n)
 Write the first n bytes following the pointer buf to the file represented by f. More...
 
bool file_readc (ang_file *f, byte *b)
 Read a byte from the file represented by f and place it at the location specified by 'b'. More...
 
bool file_writec (ang_file *f, byte b)
 Write the byte b to the file represented by f. More...
 
bool dir_exists (const char *dirname)
 

Directory code

More...
 
bool dir_create (const char *dirname)
 Create's the given directory, creating intermediate directories if needed and possible. More...
 
ang_dirmy_dopen (const char *dirname)
 Opens a directory handle. More...
 
bool my_dread (ang_dir *dir, char *fname, size_t len)
 Reads a directory entry. More...
 
void my_dclose (ang_dir *dir)
 Close a directory handle. More...
 

Variables

int player_uid
 

Permissions code

More...
 
int player_egid
 
void(* file_open_hook )(const char *path, file_type ftype)
 Platform hook for file_open. More...
 

Detailed Description

Low-level file (and directory) handling.

Copyright (c) 1997-2007 Ben Harrison, pelpel, Andi Sidwell, Matthew Jones

This work is free software; you can redistribute it and/or modify it under the terms of either:

a) the GNU General Public License as published by the Free Software Foundation, version 2, or

b) the "Angband licence": This software may be copied and distributed for educational, research, and not for profit purposes provided that this copyright and statement are included in all such copies. Other copyrights may also apply.

Typedef Documentation

typedef struct ang_dir ang_dir

An opaque file handle for Angband directory handling.

typedef struct ang_file ang_file


File access code

Data types An opaque file handle for Angband file handling.

Enumeration Type Documentation

enum file_mode

Specifies what kind of access is required to a file.

See file_open().

Enumerator
MODE_WRITE 
MODE_READ 
MODE_APPEND 
enum file_type

Specifies what kind of thing a file is, when writing.

See file_open().

Enumerator
FTYPE_TEXT 
FTYPE_SAVE 
FTYPE_RAW 
FTYPE_HTML 

Function Documentation

bool dir_create ( const char *  dirname)

Create's the given directory, creating intermediate directories if needed and possible.

Returns whether or not the directory was created successfully.

References buf, dir_exists(), my_mkdir, my_strcpy(), PATH_SEPC, and ptr.

Referenced by change_path(), create_needed_dirs(), and stats_make_output_dir().

bool dir_exists ( const char *  dirname)


Directory code

Return whether or not a directory exists.

Referenced by dir_create().

bool file_close ( ang_file f)
bool file_delete ( const char *  fname)

Tries to delete fname.

Returns true if successful, false otherwise.

Tries to delete fname.

Delete file 'fname'.

References buf, and path_parse().

Referenced by do_cmd_save_screen_html(), highscore_write(), remove_old_dump(), savefile_save(), teardown_tests(), and text_lines_to_file().

bool file_exists ( const char *  fname)

Utility functions.

Returns true if fname exists (and is a file), false otherwise.

Utility functions.

Referenced by file_archive(), get_file_text(), highscore_write(), load_sound(), process_pref_file_layered(), savefile_save(), show_splashscreen(), start_game(), stats_db_open(), test_newgame(), and text_lines_to_file().

bool file_getl ( ang_file f,
char *  buf,
size_t  n 
)

Line-based IO.

Get a line of text from the file represented by f, placing it into buf to a maximum length of n.

This expands tabs, replaces non-printables with '?', and deals with differing line endings.

Returns true when data is returned; false otherwise.

References ang_file::fh, file_readc(), i, max_len, SEEK_CUR, and TAB_COLUMNS.

Referenced by display_winner(), init_graphics_modes(), parse_file(), print_tomb(), process_pref_file_named(), remove_old_dump(), show_file(), and show_splashscreen().

void file_lock ( ang_file f)

File locking.

Lock or unlock the file represented by f for writing. If the file is not open for writing, this call will fail.

If f is closed, the file is automatically unlocked.

File locking.

Lock a file using POSIX locks, on platforms where this is supported.

References ang_file::fh, ang_file::mode, MODE_READ, and SEEK_SET.

Referenced by highscore_write().

bool file_move ( const char *  fname,
const char *  newname 
)

Moves the file fname to newname.

Returns true if successful, false otherwise.

Moves the file fname to newname.

References buf, and path_parse().

Referenced by activate_randart_file(), file_archive(), highscore_write(), remove_old_dump(), savefile_save(), and text_lines_to_file().

bool file_newer ( const char *  first,
const char *  second 
)

Returns true if the file first is newer than second.

Returns true if the file first is newer than second.

ang_file* file_open ( const char *  fname,
file_mode  mode,
file_type  ftype 
)

File handle creation.

Open file buf, returning a file handler representing that file.

The file mode specifies what kind of access is required to the file:

  • MODE_WRITE will overwrite the current contents of the file
  • MODE_READ will allow read-only access to the file
  • MODE_APPEND will allow write-only access, but will not overwrite the current contents of the file.

The file type is specified to allow systems which don't use file extensions to set the type of the file appropriately. When reading, pass -1 as ftype; when writing, use whichever filetype seems most appropriate.

On any kind of error, this function returns NULL.

File handle creation.

Returns file handle or NULL.

References buf, ang_file::fh, file_open_hook, ang_file::fname, FTYPE_SAVE, mem_free(), mem_zalloc(), ang_file::mode, MODE_APPEND, MODE_READ, MODE_WRITE, NULL, O_BINARY, open, path_parse(), S_IRUSR, S_IWUSR, string_make(), and void().

Referenced by display_winner(), do_cmd_save_screen_html(), do_randart(), highscore_read(), highscore_write(), html_screenshot(), init_graphics_modes(), object_value_real(), parse_file(), prefs_save(), print_tomb(), process_pref_file_named(), remove_old_dump(), savefile_get_description(), savefile_load(), savefile_save(), show_file(), show_splashscreen(), spoil_artifact(), spoil_mon_desc(), spoil_mon_info(), spoil_obj_desc(), and text_lines_to_file().

bool file_put ( ang_file f,
const char *  buf 
)

Write the string pointed to by buf to the file represented by f.

Returns true if successful, false otherwise.

Write the string pointed to by buf to the file represented by f.

References file_write().

Referenced by dump_history(), and file_vputf().

bool file_putf ( ang_file f,
const char *  fmt,
  ... 
)
int file_read ( ang_file f,
char *  buf,
size_t  n 
)

Reads n bytes from file 'f' into buffer 'buf'.

Returns
Number of bytes read; -1 on error

Reads n bytes from file 'f' into buffer 'buf'.

References ang_file::fh, and read.

Referenced by check_header(), highscore_read(), load_block(), and next_blockheader().

bool file_readc ( ang_file f,
byte b 
)

Read a byte from the file represented by f and place it at the location specified by 'b'.

Returns true if successful, false otherwise.

Read a byte from the file represented by f and place it at the location specified by 'b'.

References ang_file::fh, and i.

Referenced by file_getl().

bool file_skip ( ang_file f,
int  bytes 
)

Byte-based IO.

Skip 'bytes' bytes.

Returns
true if successful, false otherwise.

Byte-based IO.

Seek to location 'pos' in file 'f'.

References ang_file::fh, and SEEK_CUR.

Referenced by skip_block().

void file_unlock ( ang_file f)

Unlock a file locked using file_lock().

References ang_file::fh, and SEEK_SET.

bool file_vputf ( ang_file f,
const char *  fmt,
va_list  vp 
)

Append a formatted line of text to the end of file 'f'.

file_vputf() is the va_list version. It returns true if the write was successful and false otherwise.

References buf, file_put(), void(), and vstrnfmt().

Referenced by file_putf().

bool file_write ( ang_file f,
const char *  buf,
size_t  n 
)

Write the first n bytes following the pointer buf to the file represented by f.

Do not mix with calls to file_writec().

Returns true if successful, false otherwise.

Write the first n bytes following the pointer buf to the file represented by f.

References ang_file::fh.

Referenced by file_put(), file_writec(), highscore_write(), savefile_save(), text_out_to_file(), and try_save().

bool file_writec ( ang_file f,
byte  b 
)

Write the byte b to the file represented by f.

Returns true if successful, false otherwise.

Write the byte b to the file represented by f.

References file_write().

Referenced by spoiler_out_n_chars(), and text_out_to_file().

void my_dclose ( ang_dir dir)

Close a directory handle.

References ang_dir::d, ang_dir::dirname, and mem_free().

Referenced by list_saves().

ang_dir* my_dopen ( const char *  dirname)

Opens a directory handle.

dirname must be a system-specific pathname to the directory you want scanned.

Returns a valid directory handle on success, NULL otherwise.

References ang_dir::d, ang_dir::dirname, mem_zalloc(), NULL, and string_make().

Referenced by list_saves().

bool my_dread ( ang_dir dir,
char *  fname,
size_t  len 
)

Reads a directory entry.

dir must point to a directory handle previously returned by my_dopen(). fname must be a pointer to a writeable chunk of memory len long.

Returns true on successful reading, false otherwise. (false generally indicates that there are no more files to be read.)

References ang_dir::d, ang_dir::dirname, my_strcpy(), NULL, and path_build().

Referenced by list_saves().

size_t path_build ( char *  buf,
size_t  len,
const char *  base,
const char *  leaf 
)


Path building code

Concatenates "leaf" onto the end of "base", using system-specific path separators, and places the result in buf[], truncated to "len" bytes.

On Unixes, deals with the tilde as representing home directories.


Path building code

On Unixes, we convert a tidle at the beginning of a basename to mean the directory, complicating things a little, but better now than later.

Remember to free the return value.

References path_process(), PATH_SEP, prefix(), strnfcat(), and suffix().

Referenced by activate_randart_file(), change_path(), create_needed_dirs(), display_winner(), do_cmd_save_screen_html(), do_randart(), file_archive(), get_file_text(), get_pref_path(), highscore_read(), highscore_write(), init_file_paths(), init_graphics_modes(), list_saves(), load_sound(), lore_save(), my_dread(), object_value_real(), parse_file(), parse_graf_directory(), pile_integrity_fail(), print_tomb(), process_pref_file_layered(), reset_visuals(), save_game(), savefile_set_name(), show_file(), show_splashscreen(), spoil_artifact(), spoil_mon_desc(), spoil_mon_info(), spoil_obj_desc(), stats_db_open(), and stats_make_output_dir().

size_t path_filename_index ( const char *  path)

Return the index of the filename in a path, using PATH_SEPC.

If no path separator is found, return 0.

References i, and PATH_SEPC.

Referenced by process_character_pref_files().

void safe_setuid_drop ( void  )

Drop permissions.

References quit().

Referenced by highscore_write(), main(), prefs_save(), savefile_save(), and text_lines_to_file().

void safe_setuid_grab ( void  )

Drop or grab privileges.

This is used on multiuser systems, where the game wants to gain access to system-wide files like the scores, raw files, or savefiles. Reading from these locations is permitted by anyone, but writing to them requires a call to safe_setuid_grab() before opening the file for writing.

safe_setuid_drop() should be called immediately after the file has been opened, to prevent security risks, and restores the game's rights so that it cannot write to the system-wide files.

Drop or grab privileges.

References player_egid, and quit().

Referenced by highscore_write(), prefs_save(), savefile_save(), and text_lines_to_file().

Variable Documentation

void(* file_open_hook)(const char *path, file_type ftype)

Platform hook for file_open.

Used to set filetypes.

Platform hook for file_open.

Referenced by file_open().

int player_egid

Referenced by main(), and safe_setuid_grab().

int player_uid


Permissions code

Player's user ID and group ID, respectively.

Only relevant to POSIX systems that use main.c, and set there.


Permissions code

Referenced by build_score(), list_saves(), main(), and savefile_set_name().