BIND9 Internals: lib/isc/include/isc/file.h File Reference

Go to the source code of this file.


Defines
#define	ISC_FILE_H 1
Functions
ISC_LANG_BEGINDECLS isc_result_t	isc_file_settime (const char file, isc_time_t time)
isc_result_t	isc_file_mode (const char file, mode_t modep)
isc_result_t	isc_file_getmodtime (const char file, isc_time_t time)
	Get the time of last modification of a file.
isc_result_t	isc_file_mktemplate (const char path, char buf, size_t buflen)
	Generate a template string suitable for use with isc_file_openunique().
isc_result_t	isc_file_openunique (char templet, FILE *fp)
isc_result_t	isc_file_openuniqueprivate (char templet, FILE *fp)
isc_result_t	isc_file_openuniquemode (char templet, int mode, FILE *fp)
isc_result_t	isc_file_bopenunique (char templet, FILE *fp)
isc_result_t	isc_file_bopenuniqueprivate (char templet, FILE *fp)
isc_result_t	isc_file_bopenuniquemode (char templet, int mode, FILE *fp)
	Create and open a file with a unique name based on 'templet'. isc_file_bopen() open the file in binary mode in Windows. isc_file_open() open the file in text mode in Windows.
isc_result_t	isc_file_remove (const char *filename)
	Remove the file named by 'filename'.
isc_result_t	isc_file_rename (const char oldname, const char newname)
	Rename the file 'oldname' to 'newname'.
isc_boolean_t	isc_file_exists (const char *pathname)
	Return ISC_TRUE if the calling process can tell that the given file exists. Will not return true if the calling process has insufficient privileges to search the entire path.
isc_boolean_t	isc_file_isabsolute (const char *filename)
	Return ISC_TRUE if the given file name is absolute.
isc_result_t	isc_file_isplainfile (const char *name)
isc_result_t	isc_file_isplainfilefd (int fd)
	Check that the file is a plain file.
isc_result_t	isc_file_isdirectory (const char *name)
	Check that 'name' exists and is a directory.
isc_boolean_t	isc_file_iscurrentdir (const char *filename)
	Return ISC_TRUE if the given file name is the current directory (".").
isc_boolean_t	isc_file_ischdiridempotent (const char *filename)
	Return ISC_TRUE if calling chdir(filename) multiple times will give the same result as calling it once.
const char *	isc_file_basename (const char *filename)
	Return the final component of the path in the file name.
isc_result_t	isc_file_progname (const char filename, char buf, size_t buflen)
	Given an operating system specific file name "filename" referring to a program, return the canonical program name.
isc_result_t	isc_file_template (const char path, const char templet, char *buf, size_t buflen)
	Create an OS specific template using 'path' to define the directory 'templet' to describe the filename and store the result in 'buf' such that path can be renamed to buf atomically.
isc_result_t	isc_file_renameunique (const char file, char templet)
	Rename 'file' using 'templet' as a template for the new file name.
isc_result_t	isc_file_absolutepath (const char filename, char path, size_t pathlen)
	Given a file name, return the fully qualified path to the file.
isc_result_t	isc_file_truncate (const char *filename, isc_offset_t size)
	Truncate/extend the file specified to 'size' bytes.
isc_result_t	isc_file_safecreate (const char filename, FILE *fp)
	Open 'filename' for writing, truncating if necessary. Ensure that if it existed it was a normal file. If creating the file, ensure that only the owner can read/write it.
isc_result_t	isc_file_splitpath (isc_mem_t mctx, char path, char dirname, char basename)
	Split a path into dirname and basename. If 'path' contains no slash (or, on windows, backslash), then '*dirname' is set to ".".
isc_result_t	isc_file_getsize (const char file, off_t size)
	Return the size of the file (stored in the parameter pointed to by 'size') in bytes.
isc_result_t	isc_file_getsizefd (int fd, off_t *size)
	Return the size of the file (stored in the parameter pointed to by 'size') in bytes.
void *	isc_file_mmap (void *addr, size_t len, int prot, int flags, int fd, off_t offset)
	Portable front-end to mmap(). If mmap() is not defined on this platform, then we simulate it by calling malloc() and read(). (In this event, the addr, prot, and flags parameters are ignored).
int	isc_file_munmap (void *addr, size_t len)
	Portable front-end to munmap(). If munmap() is not defined on this platform, then we simply free the memory.
isc_result_t	isc_file_sanitize (const char dir, const char base, const char ext, char path, size_t length)
	Generate a sanitized filename, such as for MKEYS or NZF files.

Detailed Description

Define Documentation

#define ISC_FILE_H 1

Definition at line 21 of file file.h.

Function Documentation

ISC_LANG_BEGINDECLS isc_result_t isc_file_settime	(	const char *	file,
		isc_time_t *	time
	)

Definition at line 180 of file file.c.

References isc__errno2result, ISC_R_RANGE, ISC_R_SUCCESS, isc_time_nanoseconds(), isc_time_seconds(), and REQUIRE.

Referenced by setmodtime(), and zone_xfrdone().

isc_result_t isc_file_mode	(	const char *	file,
		mode_t *	modep
	)

Definition at line 130 of file file.c.

References file_stats(), ISC_R_SUCCESS, and REQUIRE.

Referenced by dst__privstruct_writefile().

isc_result_t isc_file_getmodtime	(	const char *	file,
		isc_time_t *	time
	)

Get the time of last modification of a file.

Notes:

The time that is set is relative to the (OS-specific) epoch, as are all isc_time_t structures.

Requires:

file != NULL.
time != NULL.

Ensures:

If the file could not be accessed, 'time' is unchanged.

Returns:

ISC_R_SUCCESS Success.
ISC_R_NOTFOUND No such file exists.
ISC_R_INVALIDFILE The path specified was not usable by the operating system.
ISC_R_NOPERM The file's metainformation could not be retrieved because permission was denied to some part of the file's path.
ISC_R_IOERROR Hardware error interacting with the filesystem.
ISC_R_UNEXPECTED Something totally unexpected happened.

Definition at line 144 of file file.c.

References file_stats(), ISC_R_SUCCESS, isc_time_set(), and REQUIRE.

Referenced by zone_postload(), zone_registerinclude(), and zone_touched().

isc_result_t isc_file_mktemplate	(	const char *	path,
		char *	buf,
		size_t	buflen
	)

Generate a template string suitable for use with isc_file_openunique().

Notes:

This function is intended to make creating temporary files portable between different operating systems.

The path is prepended to an implementation-defined string and placed into buf. The string has no path characters in it, and its maximum length is 14 characters plus a NUL. Thus buflen should be at least strlen(path) + 15 characters or an error will be returned.

Requires:

buf != NULL.

Ensures:

If result == ISC_R_SUCCESS: buf contains a string suitable for use as the template argument to isc_file_openunique().

If result != ISC_R_SUCCESS: buf is unchanged.

Returns:

ISC_R_SUCCESS Success.
ISC_R_NOSPACE buflen indicates buf is too small for the catenation of the path with the internal template string.

Definition at line 223 of file file.c.

References isc_file_template(), and TEMPLATE.

Referenced by destroy(), main(), and opentmp().

isc_result_t isc_file_openunique	(	char *	templet,
		FILE **	fp
	)

Definition at line 307 of file file.c.

References isc_file_openuniquemode().

Referenced by dump(), main(), nzf_remove(), and opentmp().

isc_result_t isc_file_openuniqueprivate	(	char *	templet,
		FILE **	fp
	)

Definition at line 313 of file file.c.

References isc_file_openuniquemode().

Referenced by destroy().

isc_result_t isc_file_openuniquemode	(	char *	templet,
		int	mode,
		FILE **	fp
	)

Definition at line 319 of file file.c.

References alphnum, isc__errno2result, isc_lctx, ISC_LOG_ERROR, isc_log_write(), ISC_LOGCATEGORY_GENERAL, ISC_LOGMODULE_FILE, ISC_R_FAILURE, ISC_R_SUCCESS, isc_random_get(), and REQUIRE.

Referenced by isc_file_bopenunique(), isc_file_bopenuniquemode(), isc_file_bopenuniqueprivate(), isc_file_openunique(), and isc_file_openuniqueprivate().

isc_result_t isc_file_bopenunique	(	char *	templet,
		FILE **	fp
	)

Definition at line 377 of file file.c.

References isc_file_openuniquemode().

Referenced by main(), and opentmp().

isc_result_t isc_file_bopenuniqueprivate	(	char *	templet,
		FILE **	fp
	)

Definition at line 383 of file file.c.

References isc_file_openuniquemode().

isc_result_t isc_file_bopenuniquemode	(	char *	templet,
		int	mode,
		FILE **	fp
	)

Create and open a file with a unique name based on 'templet'. isc_file_bopen*() open the file in binary mode in Windows. isc_file_open*() open the file in text mode in Windows.

Notes:

'template' is a reserved work in C++. If you want to complain about the spelling of 'templet', first look it up in the Merriam-Webster English dictionary. (http://www.m-w.com/)

This function works by using the template to generate file names. The template must be a writable string, as it is modified in place. Trailing X characters in the file name (full file name on Unix, basename on Win32 -- eg, tmp-XXXXXX vs XXXXXX.tmp, respectively) are replaced with ASCII characters until a non-existent filename is found. If the template does not include pathname information, the files in the working directory of the program are searched.

isc_file_mktemplate is a good, portable way to get a template.

Requires:

'fp' is non-NULL and '*fp' is NULL.

'template' is non-NULL, and of a form suitable for use by the system as described above.

Ensures:

If result is ISC_R_SUCCESS: *fp points to an stream opening in stdio's "w+" mode.

If result is not ISC_R_SUCCESS: *fp is NULL.

No file is open. Even if one was created (but unable to be reopened as a stdio FILE pointer) then it has been removed.

This function does *not* ensure that the template string has not been modified, even if the operation was unsuccessful.

Returns:

ISC_R_SUCCESS Success.
ISC_R_EXISTS No file with a unique name could be created based on the template.
ISC_R_INVALIDFILE The path specified was not usable by the operating system.
ISC_R_NOPERM The file could not be created because permission was denied to some part of the file's path.
ISC_R_IOERROR Hardware error interacting with the filesystem.
ISC_R_UNEXPECTED Something totally unexpected happened.

Definition at line 389 of file file.c.

References isc_file_openuniquemode().

isc_result_t isc_file_remove ( const char * filename )

Remove the file named by 'filename'.

Definition at line 394 of file file.c.

References isc__errno2result, ISC_R_SUCCESS, r, and REQUIRE.

Referenced by cleanup_session_key(), closeandrename(), dns_journal_compact(), dns_master_dumpinc3(), dns_view_saventa(), generate_session_key(), journal_file_create(), ns_server_delzone(), removetempfile(), roll_log(), and synczone().

isc_result_t isc_file_rename	(	const char *	oldname,
		const char *	newname
	)

Rename the file 'oldname' to 'newname'.

Definition at line 407 of file file.c.

References isc__errno2result, ISC_R_SUCCESS, r, and REQUIRE.

Referenced by closeandrename(), destroy(), main(), nzf_remove(), and roll_log().

isc_boolean_t isc_file_exists ( const char * pathname )

Return ISC_TRUE if the calling process can tell that the given file exists. Will not return true if the calling process has insufficient privileges to search the entire path.

Definition at line 421 of file file.c.

References file_stats(), ISC_R_SUCCESS, ISC_TF, and REQUIRE.

Referenced by get_rndckey(), inuse(), isc_file_sanitize(), parse_config(), read_confkey(), read_sessionkey(), and zone_load().

isc_boolean_t isc_file_isabsolute ( const char * filename )

Return ISC_TRUE if the given file name is absolute.

Definition at line 483 of file file.c.

References ISC_TF, and REQUIRE.

Referenced by isc_file_ischdiridempotent(), and setup().

isc_result_t isc_file_isplainfile ( const char * name )

Definition at line 430 of file file.c.

References isc__errno2result, ISC_R_INVALIDFILE, and ISC_R_SUCCESS.

Referenced by channel_fromconf().

isc_result_t isc_file_isplainfilefd ( int fd )

Check that the file is a plain file.

Returns:

ISC_R_SUCCESS Success. The file is a plain file.
ISC_R_INVALIDFILE The path specified was not usable by the operating system.
ISC_R_FILENOTFOUND The file does not exist. This return code comes from errno=ENOENT when stat returns -1. This code is mentioned here, because in logconf.c, it is the one rcode that is permitted in addition to ISC_R_SUCCESS. This is done since the next call in logconf.c is to isc_stdio_open(), which will create the file if it can.
other ISC_R_* errors translated from errno These occur when stat returns -1 and an errno.

Definition at line 447 of file file.c.

References isc__errno2result, ISC_R_INVALIDFILE, and ISC_R_SUCCESS.

Referenced by dns_rbt_serialize_tree(), and serialize().

isc_result_t isc_file_isdirectory ( const char * name )

Check that 'name' exists and is a directory.

Returns:

ISC_R_SUCCESS Success, file is a directory.
ISC_R_INVALIDFILE File is not a directory.
ISC_R_FILENOTFOUND File does not exist.
other ISC_R_* errors translated from errno These occur when stat returns -1 and an errno.

Definition at line 464 of file file.c.

References isc__errno2result, ISC_R_INVALIDFILE, and ISC_R_SUCCESS.

Referenced by check_zoneconf(), and configure_view_dnsseckeys().

isc_boolean_t isc_file_iscurrentdir ( const char * filename )

Return ISC_TRUE if the given file name is the current directory (".").

Definition at line 489 of file file.c.

References ISC_TF, and REQUIRE.

Referenced by isc_file_ischdiridempotent().

isc_boolean_t isc_file_ischdiridempotent ( const char * filename )

Return ISC_TRUE if calling chdir(filename) multiple times will give the same result as calling it once.

Definition at line 495 of file file.c.

References ISC_FALSE, isc_file_isabsolute(), isc_file_iscurrentdir(), ISC_TRUE, and REQUIRE.

Referenced by directory_callback().

const char* isc_file_basename ( const char * filename )

Return the final component of the path in the file name.

Definition at line 505 of file file.c.

References REQUIRE, and s.

Referenced by isc_file_progname(), and setup_syslog().

isc_result_t isc_file_progname	(	const char *	filename,
		char *	buf,
		size_t	buflen
	)

Given an operating system specific file name "filename" referring to a program, return the canonical program name.

Any directory prefix or executable file name extension (if used on the OS in case) is stripped. On systems where program names are case insensitive, the name is canonicalized to all lower case. The name is written to 'buf', an array of 'buflen' chars, and null terminated.

Returns:

ISC_R_SUCCESS
ISC_R_NOSPACE The name did not fit in 'buf'.

Definition at line 518 of file file.c.

References isc_file_basename(), ISC_R_NOSPACE, ISC_R_SUCCESS, and REQUIRE.

Referenced by main().

isc_result_t isc_file_template	(	const char *	path,
		const char *	templet,
		char *	buf,
		size_t	buflen
	)

Create an OS specific template using 'path' to define the directory 'templet' to describe the filename and store the result in 'buf' such that path can be renamed to buf atomically.

Definition at line 228 of file file.c.

References ISC_R_NOSPACE, ISC_R_SUCCESS, REQUIRE, and s.

Referenced by isc_file_mktemplate(), nzf_remove(), and zone_saveunique().

isc_result_t isc_file_renameunique	(	const char *	file,
		char *	templet
	)

Rename 'file' using 'templet' as a template for the new file name.

Definition at line 263 of file file.c.

References alphnum, isc__errno2result, ISC_R_FAILURE, ISC_R_SUCCESS, isc_random_get(), and REQUIRE.

Referenced by zone_saveunique().

isc_result_t isc_file_absolutepath	(	const char *	filename,
		char *	path,
		size_t	pathlen
	)

Given a file name, return the fully qualified path to the file.

Definition at line 567 of file file.c.

References dir_current(), ISC_R_NOSPACE, and ISC_R_SUCCESS.

Referenced by setup().

isc_result_t isc_file_truncate	(	const char *	filename,
		isc_offset_t	size
	)

Truncate/extend the file specified to 'size' bytes.

Definition at line 579 of file file.c.

References isc__errno2result, and ISC_R_SUCCESS.

isc_result_t isc_file_safecreate	(	const char *	filename,
		FILE **	fp
	)

Open 'filename' for writing, truncating if necessary. Ensure that if it existed it was a normal file. If creating the file, ensure that only the owner can read/write it.

Definition at line 588 of file file.c.

References file_stats(), isc__errno2result, ISC_R_FILENOTFOUND, ISC_R_INVALIDFILE, ISC_R_SUCCESS, and REQUIRE.

isc_result_t isc_file_splitpath	(	isc_mem_t *	mctx,
		char *	path,
		char **	dirname,
		char **	basename
	)

Split a path into dirname and basename. If 'path' contains no slash (or, on windows, backslash), then '*dirname' is set to ".".

Allocates memory for '*dirname', which can be freed with isc_mem_free().

Returns:

ISC_R_SUCCESS on success
ISC_R_INVALIDFILE if 'path' is empty or ends with '/'
ISC_R_NOMEMORY if unable to allocate memory

Definition at line 624 of file file.c.

References isc_mem_allocate, isc_mem_free, isc_mem_strdup, ISC_R_INVALIDFILE, ISC_R_NOMEMORY, and ISC_R_SUCCESS.

Referenced by main().

isc_result_t isc_file_getsize	(	const char *	file,
		off_t *	size
	)

Return the size of the file (stored in the parameter pointed to by 'size') in bytes.

Returns:

ISC_R_SUCCESS on success

Definition at line 164 of file file.c.

References file_stats(), ISC_R_SUCCESS, and REQUIRE.

isc_result_t isc_file_getsizefd	(	int	fd,
		off_t *	size
	)

Return the size of the file (stored in the parameter pointed to by 'size') in bytes.

Returns:

ISC_R_SUCCESS on success

Definition at line 115 of file file.c.

References fd_stats(), ISC_R_SUCCESS, and REQUIRE.

Referenced by ATF_TC_BODY(), and deserialize32().

void* isc_file_mmap	(	void *	addr,
		size_t	len,
		int	prot,
		int	flags,
		int	fd,
		off_t	offset
	)

Portable front-end to mmap(). If mmap() is not defined on this platform, then we simulate it by calling malloc() and read(). (In this event, the addr, prot, and flags parameters are ignored).

Definition at line 661 of file file.c.

References free(), and UNUSED.

Referenced by deserialize32().

int isc_file_munmap	(	void *	addr,
		size_t	len
	)

Portable front-end to munmap(). If munmap() is not defined on this platform, then we simply free the memory.

Definition at line 692 of file file.c.

References free(), and UNUSED.

Referenced by free_rbtdb().

isc_result_t isc_file_sanitize	(	const char *	dir,
		const char *	base,
		const char *	ext,
		char *	path,
		size_t	length
	)

Generate a sanitized filename, such as for MKEYS or NZF files.

Historically, MKEYS and NZF files used SHA256 hashes of the view name for the filename; this was to deal with the possibility of forbidden characters such as "/" being in a view name, and to avoid problems with case-insensitive file systems.

Given a basename 'base' and an extension 'ext', this function checks for the existence of file using the old-style name format in directory 'dir'. If found, it returns the path to that file. If there is no file already in place, a new pathname is generated; if the basename contains any excluded characters, then a truncated SHA256 hash is used, otherwise the basename is used. The path name is copied into 'path', which must point to a buffer of at least 'length' bytes.

Requires:

base != NULL
path != NULL

Returns:

ISC_R_SUCCESS on success
ISC_R_NOSPACE if the resulting path would be longer than 'length'

Definition at line 709 of file file.c.

References DISALLOW, hash, isc_file_exists(), ISC_R_NOSPACE, ISC_R_SUCCESS, isc_sha256_data(), PATH_MAX, and REQUIRE.

Referenced by add_keydata_zone(), ATF_TC_BODY(), ATF_TP_ADD_TCS(), dns_view_create(), and dns_view_setnewzones().

file.h File Reference

Defines

Functions

Detailed Description

Define Documentation

Function Documentation