xref: /haiku/docs/user/storage/File.dox (revision 90ae2e54f6ccaca73c011a2aa4cdd660417108ad)
1/*
2 * Copyright 2009-2012 Haiku, Inc. All rights reserved.
3 * Distributed under the terms of the MIT License.
4 *
5 * Authors:
6 *		Tyler Dauwalder
7 *		John Scipione, jscipione@gmail.com
8 *		Ingo Weinhold, bonefish@users.sf.net
9 *
10 * Corresponds to:
11 *		headers/os/storage/File.h  hrev45060
12 *		src/kits/storage/File.cpp  hrev45060
13 */
14
15
16/*!
17	\file File.h
18	\brief Provides the BFile class.
19*/
20
21
22/*!
23	\class BFile
24	\ingroup storage
25	\ingroup libbe
26	\brief Provides the ability to read and write the data of a file.
27
28	The file is automatically opened when you initialize a BFile and is
29	automatically closed when you re-initialize or destroy the object.
30
31	Symbolic links are automatically transversed by opening a BFile.
32	The node that the BFile ends up opening will be the file or directory
33	that the link points to, not the symbolic link file itself.
34*/
35
36
37/*!
38	\fn BFile::BFile()
39	\brief Creates an uninitialized BFile object.
40
41	Should be followed by a call to one of the SetTo() methods, or an
42	assignment:
43	- SetTo(const entry_ref* ref, uint32 openMode)
44	- SetTo(const BEntry* entry, uint32 openMode)
45	- SetTo(const char* path, uint32 openMode)
46	- SetTo(const BDirectory* dir, const char* path, uint32 openMode)
47	- operator=(const BFile &file)
48*/
49
50
51/*!
52	\fn BFile::BFile(const BFile& file)
53	\brief Creates a copy of the supplied BFile.
54
55	If \a file is uninitialized, the newly constructed BFile will be too.
56
57	\param file The BFile object to be copied.
58*/
59
60
61/*!
62	\fn BFile::BFile(const entry_ref* ref, uint32 openMode)
63	\brief Creates a BFile and initializes it to the file referred to by
64		   the supplied entry_ref and according to the specified open mode.
65
66	\param ref The entry_ref referring to the file.
67	\param openMode The mode in which the file should be opened.
68
69	\see SetTo(const entry_ref* ref, uint32 openMode)
70*/
71
72
73/*!
74	\fn BFile::BFile(const BEntry* entry, uint32 openMode)
75	\brief Creates a BFile and initializes it to the file referred to by
76		   the supplied BEntry and according to the specified open mode.
77
78	\param entry The BEntry referring to the file.
79	\param openMode The mode in which the file should be opened.
80
81	\see SetTo(const BEntry* entry, uint32 openMode)
82*/
83
84
85/*!
86	\fn BFile::BFile(const char* path, uint32 openMode)
87	\brief Creates a BFile and initializes it to the file referred to by
88		   the supplied path name and according to the specified open mode.
89
90	\param path The file's path name.
91	\param openMode The mode in which the file should be opened.
92
93	\see SetTo(const char* path, uint32 openMode)
94*/
95
96
97/*!
98	\fn BFile::BFile(const BDirectory *dir, const char* path, uint32 openMode)
99	\brief Creates a BFile and initializes it to the file referred to by
100		   the supplied path name relative to the specified BDirectory and
101		   according to the specified open mode.
102
103	\param dir The BDirectory, relative to which the file's path name is
104		   given.
105	\param path The file's path name relative to \a dir.
106	\param openMode The mode in which the file should be opened.
107
108	\see SetTo(const BDirectory* dir, const char* path, uint32 openMode)
109*/
110
111
112/*!
113	\fn BFile::~BFile()
114	\brief Destroys the BFile object and frees all allocated resources.
115
116	If the file is properly initialized, the file descriptor is closed.
117*/
118
119
120/*!
121	\fn status_t BFile::SetTo(const entry_ref* ref, uint32 openMode)
122	\brief Re-initializes the BFile to the file referred to by the
123		   supplied entry_ref and according to the specified open mode.
124
125	\param ref The entry_ref referring to the file.
126	\param openMode The mode in which the file should be opened
127		\a openMode must be a bitwise or of exactly one of the flags.
128		- \c B_READ_ONLY: The file is opened read only.
129		- \c B_WRITE_ONLY: The file is opened write only.
130		- \c B_READ_WRITE: The file is opened for random read/write access.
131		and any number of the flags
132		- \c B_CREATE_FILE: A new file will be created, if it does not already
133			exist.
134		- \c B_FAIL_IF_EXISTS: If the file does already exist and
135			\c B_CREATE_FILE is set, SetTo() fails.
136		- \c B_ERASE_FILE: An already existing file is truncated to zero size.
137		- \c B_OPEN_AT_END: Seek() to the end of the file after opening.
138
139	\returns A status code.
140	\retval B_OK Everything went fine.
141	\retval B_BAD_VALUE \c NULL \a ref or bad \a openMode.
142	\retval B_ENTRY_NOT_FOUND File not found or failed to create file.
143	\retval B_FILE_EXISTS File exists and \c B_FAIL_IF_EXISTS was passed.
144	\retval B_PERMISSION_DENIED File permissions didn't allow operation.
145	\retval B_NO_MEMORY Insufficient memory for operation.
146	\retval B_LINK_LIMIT Indicates a cyclic loop within the file system.
147	\retval B_BUSY A node was busy.
148	\retval B_FILE_ERROR A general file error.
149	\retval B_NO_MORE_FDS The application has run out of file descriptors.
150*/
151
152
153/*!
154	\fn status_t BFile::SetTo(const BEntry* entry, uint32 openMode)
155	\brief Re-initializes the BFile to the file referred to by the
156		   supplied BEntry and according to the specified open mode.
157
158	\param entry the BEntry referring to the file
159	\param openMode the mode in which the file should be opened
160
161	\returns A status code.
162	\retval B_OK Everything went fine.
163	\retval B_BAD_VALUE \c NULL \a entry or bad \a openMode.
164	\retval B_ENTRY_NOT_FOUND File not found or failed to create file.
165	\retval B_FILE_EXISTS File exists and \c B_FAIL_IF_EXISTS was passed.
166	\retval B_PERMISSION_DENIED File permissions didn't allow operation.
167	\retval B_NO_MEMORY Insufficient memory for operation.
168	\retval B_LINK_LIMIT Indicates a cyclic loop within the file system.
169	\retval B_BUSY A node was busy.
170	\retval B_FILE_ERROR A general file error.
171	\retval B_NO_MORE_FDS The application has run out of file descriptors.
172
173	\todo Implemented using SetTo(entry_ref*, uint32). Check, if necessary
174		  to re-implement!
175*/
176
177
178/*!
179	\fn status_t BFile::SetTo(const char* path, uint32 openMode)
180	\brief Re-initializes the BFile to the file referred to by the
181		   supplied path name and according to the specified open mode.
182
183	\param path The file's path name.
184	\param openMode The mode in which the file should be opened.
185
186	\returns A status code.
187	\retval B_OK Everything went fine.
188	\retval B_BAD_VALUE \c NULL \a path or bad \a openMode.
189	\retval B_ENTRY_NOT_FOUND File not found or failed to create file.
190	\retval B_FILE_EXISTS File exists and \c B_FAIL_IF_EXISTS was passed.
191	\retval B_PERMISSION_DENIED File permissions didn't allow operation.
192	\retval B_NO_MEMORY Insufficient memory for operation.
193	\retval B_LINK_LIMIT Indicates a cyclic loop within the file system.
194	\retval B_BUSY A node was busy.
195	\retval B_FILE_ERROR A general file error.
196	\retval B_NO_MORE_FDS The application has run out of file descriptors.
197*/
198*/
199
200
201/*!
202	\fn status_t BFile::SetTo(const BDirectory* dir, const char* path,
203		uint32 openMode)
204	\brief Re-initializes the BFile to the file referred to by the
205		   supplied path name relative to the specified BDirectory and
206		   according to the specified open mode.
207
208	\param dir The BDirectory, relative to which the file's path name is
209		   given.
210	\param path The file's path name relative to \a dir.
211	\param openMode The mode in which the file should be opened.
212
213	\returns A status code.
214	\retval B_OK Everything went fine.
215	\retval B_BAD_VALUE \c NULL \a dir or \a path or bad \a openMode.
216	\retval B_ENTRY_NOT_FOUND File not found or failed to create file.
217	\retval B_FILE_EXISTS File exists and \c B_FAIL_IF_EXISTS was passed.
218	\retval B_PERMISSION_DENIED File permissions didn't allow operation.
219	\retval B_NO_MEMORY Insufficient memory for operation.
220	\retval B_LINK_LIMIT Indicates a cyclic loop within the file system.
221	\retval B_BUSY A node was busy.
222	\retval B_FILE_ERROR A general file error.
223	\retval B_NO_MORE_FDS The application has run out of file descriptors.
224
225	\todo Implemented using SetTo(BEntry*, uint32). Check, if necessary
226		  to re-implement!
227*/
228
229
230/*!
231	\fn bool BFile::IsReadable() const
232	\brief Reports whether or not the file is readable.
233
234	\return
235	- \c true, if the BFile has been initialized properly and the file has
236	  been been opened for reading,
237	- \c false, otherwise.
238*/
239
240
241/*!
242	\fn bool BFile::IsWritable() const
243	\brief Reports whether or not the file is writable.
244
245	\return
246	- \c true, if the BFile has been initialized properly and the file has
247	  been opened for writing,
248	- \c false, otherwise.
249*/
250
251
252/*!
253	ssize_t BFile::Read(void* buffer, size_t size)
254	\brief Reads a number of bytes from the file into a buffer.
255
256	\param buffer The buffer the data from the file shall be written to.
257	\param size The number of bytes that shall be read.
258
259	\returns The number of bytes read or an error code.
260*/
261
262
263/*!
264	\fn ssize_t BFile::ReadAt(off_t location, void* buffer, size_t size)
265	\brief Reads a number of bytes from a certain position within the file
266		   into a buffer.
267
268	\param location The position (in bytes) within the file from which the
269		   data shall be read.
270	\param buffer The buffer the data from the file shall be written to.
271	\param size The number of bytes that shall be read.
272
273	\returns The number of bytes read or an error code.
274*/
275
276
277/*!
278	\fn ssize_t BFile::Write(const void* buffer, size_t size)
279	\brief Writes a number of bytes from a buffer into the file.
280
281	\param buffer The buffer containing the data to be written to the file.
282	\param size The number of bytes that shall be written.
283
284	\returns The number of bytes actually written or an error code.
285*/
286
287
288/*!
289	\fn ssize_t BFile::WriteAt(off_t location, const void* buffer, size_t size)
290	\brief \brief Writes a number of bytes from a buffer at a certain position
291		   into the file.
292
293	\param location The position (in bytes) within the file at which the data
294		   shall be written.
295	\param buffer The buffer containing the data to be written to the file.
296	\param size The number of bytes that shall be written.
297
298	\returns The number of bytes actually written or an error code.
299*/
300
301
302/*!
303	\fn off_t BFile::Seek(off_t offset, uint32 seekMode)
304	\brief Seeks to another read/write position within the file.
305
306	It is allowed to seek past the end of the file. A subsequent call to
307	Write() will pad the file with undefined data. Seeking before the
308	beginning of the file will fail and the behavior of subsequent Read()
309	or Write() invocations will be undefined.
310
311	\param offset New read/write position, depending on \a seekMode relative
312		   to the beginning or the end of the file or the current position.
313	\param seekMode
314		- \c SEEK_SET: move relative to the beginning of the file
315		- \c SEEK_CUR: move relative to the current position
316		- \c SEEK_END: move relative to the end of the file
317
318	\returns The new read/write position relative to the beginning of the
319		file or an error code.
320	\retval B_ERROR Trying to seek before the beginning of the file.
321	\retval B_FILE_ERROR The file is not properly initialized.
322*/
323
324
325/*!
326	\fn off_t BFile::Position() const
327	\brief Gets the current read/write position within the file.
328
329	\returns The current read/write position relative to the beginning of the
330		file or an error code.
331	\retval B_ERROR After a Seek() before the beginning of the file.
332	\retval B_FILE_ERROR The file has not been initialized.
333*/
334
335
336/*!
337	\fn status_t BFile::SetSize(off_t size)
338	\brief Sets the size of the file.
339
340	If the file is shorter than \a size bytes it will be padded with
341	unspecified data to the requested size. If it is larger, it will be
342	truncated.
343
344	\note There's no problem with setting the size of a BFile opened in
345		  \c B_READ_ONLY mode, unless the file resides on a read only volume.
346
347	\param size The new file size.
348
349	\returns A status code.
350	\retval B_OK Everything went fine.
351	\retval B_NOT_ALLOWED Trying to set the size of a file on a read only
352			volume.
353	\retval B_DEVICE_FULL There's not enough space left on the volume.
354*/
355
356
357/*!
358	\fn status_t BFile::GetSize(off_t* size) const
359	\brief Gets the size of the file.
360
361	\param size The file size to fill out.
362
363	\returns A status code.
364
365	\see BStatable::GetSize()
366*/
367
368
369/*!
370	\fn BFile& BFile::operator=(const BFile &file)
371	\brief Assigns another BFile to this BFile.
372
373	If the other BFile is uninitialized, this one will be too. Otherwise it
374	will refer to the same file using the same mode, unless an error occurs.
375
376	\param file The original BFile to assign from.
377
378	\returns A reference to the assigned BFile.
379*/
380
381
382/*!
383	\fn int BFile::get_fd() const
384	\brief Gets the file descriptor of the BFile.
385
386	To be used instead of accessing the BNode's private \c fFd member directly.
387
388	\returns The file descriptor, or -1 if not properly initialized.
389*/
390
391
392/*!
393	\fn void BFile::close_fd()
394	\brief Overrides BNode::close_fd() for binary compatibility with BeOS R5.
395*/
396