2
* Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC")
2
* Copyright (C) 2004-2007 Internet Systems Consortium, Inc. ("ISC")
3
3
* Copyright (C) 2000, 2001 Internet Software Consortium.
5
* Permission to use, copy, modify, and distribute this software for any
5
* Permission to use, copy, modify, and/or distribute this software for any
6
6
* purpose with or without fee is hereby granted, provided that the above
7
7
* copyright notice and this permission notice appear in all copies.
34
36
isc_file_getmodtime(const char *file, isc_time_t *time);
36
* Get the time of last modication of a file.
38
* \brief Get the time of last modication of a file.
39
* The time that is set is relative to the (OS-specific) epoch, as are
41
*\li The time that is set is relative to the (OS-specific) epoch, as are
40
42
* all isc_time_t structures.
47
* If the file could not be accessed, 'time' is unchanged.
49
*\li If the file could not be accessed, 'time' is unchanged.
53
55
* No such file exists.
56
*\li #ISC_R_INVALIDFILE
55
57
* The path specified was not usable by the operating system.
57
59
* The file's metainformation could not be retrieved because
58
60
* permission was denied to some part of the file's path.
60
62
* Hardware error interacting with the filesystem.
63
*\li #ISC_R_UNEXPECTED
62
64
* Something totally unexpected happened.
67
69
isc_file_mktemplate(const char *path, char *buf, size_t buflen);
69
* Generate a template string suitable for use with isc_file_openunique.
71
* \brief Generate a template string suitable for use with isc_file_openunique().
72
* This function is intended to make creating temporary files
74
*\li This function is intended to make creating temporary files
73
75
* portable between different operating systems.
75
* The path is prepended to an implementation-defined string and
77
*\li The path is prepended to an implementation-defined string and
76
78
* placed into buf. The string has no path characters in it,
77
79
* and its maximum length is 14 characters plus a NUL. Thus
78
80
* buflen should be at least strlen(path) + 15 characters or
79
81
* an error will be returned.
85
* If result == ISC_R_SUCCESS:
87
*\li If result == #ISC_R_SUCCESS:
86
88
* buf contains a string suitable for use as the template argument
87
* to isc_file_openunique.
89
* to isc_file_openunique().
89
* If result != ISC_R_SUCCESS:
91
*\li If result != #ISC_R_SUCCESS:
90
92
* buf is unchanged.
93
* ISC_R_SUCCESS Success.
94
* ISC_R_NOSPACE buflen indicates buf is too small for the catenation
95
*\li #ISC_R_SUCCESS Success.
96
*\li #ISC_R_NOSPACE buflen indicates buf is too small for the catenation
95
97
* of the path with the internal template string.
100
102
isc_file_openunique(char *templet, FILE **fp);
102
* Create and open a file with a unique name based on 'templet'.
104
* \brief Create and open a file with a unique name based on 'templet'.
105
* 'template' is a reserved work in C++. If you want to complain
107
*\li 'template' is a reserved work in C++. If you want to complain
106
108
* about the spelling of 'templet', first look it up in the
107
109
* Merriam-Webster English dictionary. (http://www.m-w.com/)
109
* This function works by using the template to generate file names.
111
*\li This function works by using the template to generate file names.
110
112
* The template must be a writable string, as it is modified in place.
111
113
* Trailing X characters in the file name (full file name on Unix,
112
114
* basename on Win32 -- eg, tmp-XXXXXX vs XXXXXX.tmp, respectively)
114
116
* is found. If the template does not include pathname information,
115
117
* the files in the working directory of the program are searched.
117
* isc_file_mktemplate is a good, portable way to get a template.
119
*\li isc_file_mktemplate is a good, portable way to get a template.
120
* 'fp' is non-NULL and '*fp' is NULL.
122
*\li 'fp' is non-NULL and '*fp' is NULL.
122
* 'template' is non-NULL, and of a form suitable for use by
124
*\li 'template' is non-NULL, and of a form suitable for use by
123
125
* the system as described above.
126
* If result is ISC_R_SUCCESS:
128
*\li If result is #ISC_R_SUCCESS:
127
129
* *fp points to an stream opening in stdio's "w+" mode.
129
* If result is not ISC_R_SUCCESS:
131
*\li If result is not #ISC_R_SUCCESS:
132
134
* No file is open. Even if one was created (but unable
133
135
* to be reopened as a stdio FILE pointer) then it has been
136
* This function does *not* ensure that the template string has not been
138
*\li This function does *not* ensure that the template string has not been
137
139
* modified, even if the operation was unsuccessful.
143
145
* No file with a unique name could be created based on the
147
*\li #ISC_R_INVALIDFILE
146
148
* The path specified was not usable by the operating system.
148
150
* The file could not be created because permission was denied
149
151
* to some part of the file's path.
151
153
* Hardware error interacting with the filesystem.
154
*\li #ISC_R_UNEXPECTED
153
155
* Something totally unexpected happened.
157
159
isc_file_remove(const char *filename);
159
* Remove the file named by 'filename'.
161
* \brief Remove the file named by 'filename'.
163
165
isc_file_rename(const char *oldname, const char *newname);
165
* Rename the file 'oldname' to 'newname'.
167
* \brief Rename the file 'oldname' to 'newname'.
169
171
isc_file_exists(const char *pathname);
171
* Return ISC_TRUE iff the calling process can tell that the given file exists.
173
* \brief Return #ISC_TRUE if the calling process can tell that the given file exists.
172
174
* Will not return true if the calling process has insufficient privileges
173
175
* to search the entire path.
177
179
isc_file_isabsolute(const char *filename);
179
* Return ISC_TRUE iff the given file name is absolute.
181
* \brief Return #ISC_TRUE if the given file name is absolute.
183
185
isc_file_iscurrentdir(const char *filename);
185
* Return ISC_TRUE iff the given file name is the current directory (".").
187
* \brief Return #ISC_TRUE if the given file name is the current directory (".").
189
191
isc_file_ischdiridempotent(const char *filename);
191
* Return ISC_TRUE if calling chdir(filename) multiple times will give
193
* Return #ISC_TRUE if calling chdir(filename) multiple times will give
192
194
* the same result as calling it once.
196
198
isc_file_basename(const char *filename);
198
200
* Return the final component of the path in the file name.
202
204
isc_file_progname(const char *filename, char *buf, size_t buflen);
204
* Given an operating system specific file name "filename"
206
* \brief Given an operating system specific file name "filename"
205
207
* referring to a program, return the canonical program name.
206
210
* Any directory prefix or executable file name extension (if
207
211
* used on the OS in case) is stripped. On systems where program
208
212
* names are case insensitive, the name is canonicalized to all