1 //===-- File.h --------------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_File_h_
11 #define liblldb_File_h_
12 #if defined(__cplusplus)
16 #include "lldb/lldb-private.h"
18 namespace lldb_private {
20 //----------------------------------------------------------------------
21 /// @class File File.h "lldb/Host/File.h"
22 /// @brief A file class.
24 /// A file class that divides abstracts the LLDB core from host file
26 //----------------------------------------------------------------------
30 static int kInvalidDescriptor;
31 static FILE * kInvalidStream;
35 eOpenOptionRead = (1u << 0), // Open file for reading
36 eOpenOptionWrite = (1u << 1), // Open file for writing
37 eOpenOptionAppend = (1u << 2), // Don't truncate file when opening, append to end of file
38 eOpenOptionTruncate = (1u << 3), // Truncate file when opening
39 eOpenOptionNonBlocking = (1u << 4), // File reads
40 eOpenOptionCanCreate = (1u << 5), // Create file if doesn't already exist
41 eOpenOptionCanCreateNewOnly = (1u << 6) // Can create file only if it doesn't already exist
46 ePermissionsUserRead = (1u << 0),
47 ePermissionsUserWrite = (1u << 1),
48 ePermissionsUserExecute = (1u << 2),
49 ePermissionsGroupRead = (1u << 3),
50 ePermissionsGroupWrite = (1u << 4),
51 ePermissionsGroupExecute = (1u << 5),
52 ePermissionsWorldRead = (1u << 6),
53 ePermissionsWorldWrite = (1u << 7),
54 ePermissionsWorldExecute = (1u << 8),
56 ePermissionsUserRW = (ePermissionsUserRead | ePermissionsUserWrite | 0 ),
57 ePermissionsUserRX = (ePermissionsUserRead | 0 | ePermissionsUserExecute ),
58 ePermissionsUserRWX = (ePermissionsUserRead | ePermissionsUserWrite | ePermissionsUserExecute ),
60 ePermissionsGroupRW = (ePermissionsGroupRead | ePermissionsGroupWrite | 0 ),
61 ePermissionsGroupRX = (ePermissionsGroupRead | 0 | ePermissionsGroupExecute ),
62 ePermissionsGroupRWX = (ePermissionsGroupRead | ePermissionsGroupWrite | ePermissionsGroupExecute ),
64 ePermissionsWorldRW = (ePermissionsWorldRead | ePermissionsWorldWrite | 0 ),
65 ePermissionsWorldRX = (ePermissionsWorldRead | 0 | ePermissionsWorldExecute ),
66 ePermissionsWorldRWX = (ePermissionsWorldRead | ePermissionsWorldWrite | ePermissionsWorldExecute ),
68 ePermissionsEveryoneR = (ePermissionsUserRead | ePermissionsGroupRead | ePermissionsWorldRead ),
69 ePermissionsEveryoneW = (ePermissionsUserWrite | ePermissionsGroupWrite | ePermissionsWorldWrite ),
70 ePermissionsEveryoneX = (ePermissionsUserExecute | ePermissionsGroupExecute | ePermissionsWorldExecute ),
72 ePermissionsEveryoneRW = (ePermissionsEveryoneR | ePermissionsEveryoneW | 0 ),
73 ePermissionsEveryoneRX = (ePermissionsEveryoneR | 0 | ePermissionsEveryoneX ),
74 ePermissionsEveryoneRWX = (ePermissionsEveryoneR | ePermissionsEveryoneW | ePermissionsEveryoneX ),
75 ePermissionsDefault = (ePermissionsUserRW | ePermissionsGroupRead)
79 m_descriptor (kInvalidDescriptor),
80 m_stream (kInvalidStream),
86 File (FILE *fh, bool transfer_ownership) :
87 m_descriptor (kInvalidDescriptor),
90 m_owned (transfer_ownership)
94 File (const File &rhs);
97 operator= (const File &rhs);
98 //------------------------------------------------------------------
99 /// Constructor with path.
101 /// Takes a path to a file which can be just a filename, or a full
102 /// path. If \a path is not NULL or empty, this function will call
103 /// File::Open (const char *path, uint32_t options, uint32_t permissions).
106 /// The full or partial path to a file.
108 /// @param[in] options
109 /// Options to use when opening (see File::OpenOptions)
111 /// @param[in] permissions
112 /// Options to use when opening (see File::Permissions)
114 /// @see File::Open (const char *path, uint32_t options, uint32_t permissions)
115 //------------------------------------------------------------------
116 File (const char *path,
118 uint32_t permissions = ePermissionsDefault);
121 File (int fd, bool tranfer_ownership) :
123 m_stream (kInvalidStream),
125 m_owned (tranfer_ownership)
128 //------------------------------------------------------------------
131 /// The destructor is virtual in case this class is subclassed.
132 //------------------------------------------------------------------
139 return DescriptorIsValid() || StreamIsValid();
142 //------------------------------------------------------------------
143 /// Convert to pointer operator.
145 /// This allows code to check a File object to see if it
146 /// contains anything valid using code such as:
155 /// A pointer to this object if either the directory or filename
156 /// is valid, NULL otherwise.
157 //------------------------------------------------------------------
161 return DescriptorIsValid() || StreamIsValid();
164 //------------------------------------------------------------------
165 /// Logical NOT operator.
167 /// This allows code to check a File object to see if it is
168 /// invalid using code such as:
177 /// Returns \b true if the object has an empty directory and
178 /// filename, \b false otherwise.
179 //------------------------------------------------------------------
183 return !DescriptorIsValid() && !StreamIsValid();
186 //------------------------------------------------------------------
187 /// Get the file spec for this file.
190 /// A reference to the file specification object.
191 //------------------------------------------------------------------
193 GetFileSpec (FileSpec &file_spec) const;
195 //------------------------------------------------------------------
196 /// Open a file for read/writing with the specified options.
198 /// Takes a path to a file which can be just a filename, or a full
202 /// The full or partial path to a file.
204 /// @param[in] options
205 /// Options to use when opening (see File::OpenOptions)
207 /// @param[in] permissions
208 /// Options to use when opening (see File::Permissions)
209 //------------------------------------------------------------------
211 Open (const char *path,
213 uint32_t permissions = ePermissionsDefault);
219 Duplicate (const File &rhs);
222 GetDescriptor() const;
225 SetDescriptor(int fd, bool transfer_ownership);
231 SetStream (FILE *fh, bool transfer_ownership);
233 //------------------------------------------------------------------
234 /// Read bytes from a file from the current file position.
236 /// NOTE: This function is NOT thread safe. Use the read function
237 /// that takes an "off_t &offset" to ensure correct operation in
238 /// multi-threaded environments.
241 /// A buffer where to put the bytes that are read.
243 /// @param[in/out] num_bytes
244 /// The number of bytes to read form the current file position
245 /// which gets modified with the number of bytes that were read.
248 /// An error object that indicates success or the reason for
250 //------------------------------------------------------------------
252 Read (void *buf, size_t &num_bytes);
254 //------------------------------------------------------------------
255 /// Write bytes to a file at the current file position.
257 /// NOTE: This function is NOT thread safe. Use the write function
258 /// that takes an "off_t &offset" to ensure correct operation in
259 /// multi-threaded environments.
262 /// A buffer where to put the bytes that are read.
264 /// @param[in/out] num_bytes
265 /// The number of bytes to write to the current file position
266 /// which gets modified with the number of bytes that were
270 /// An error object that indicates success or the reason for
272 //------------------------------------------------------------------
274 Write (const void *buf, size_t &num_bytes);
276 //------------------------------------------------------------------
277 /// Seek to an offset relative to the beginning of the file.
279 /// NOTE: This function is NOT thread safe, other threads that
280 /// access this object might also change the current file position.
281 /// For thread safe reads and writes see the following functions:
282 /// @see File::Read (void *, size_t, off_t &)
283 /// @see File::Write (const void *, size_t, off_t &)
285 /// @param[in] offset
286 /// The offset to seek to within the file relative to the
287 /// beginning of the file.
289 /// @param[in] error_ptr
290 /// A pointer to a lldb_private::Error object that will be
291 /// filled in if non-NULL.
294 /// The resulting seek offset, or -1 on error.
295 //------------------------------------------------------------------
297 SeekFromStart (off_t offset, Error *error_ptr = NULL);
299 //------------------------------------------------------------------
300 /// Seek to an offset relative to the current file position.
302 /// NOTE: This function is NOT thread safe, other threads that
303 /// access this object might also change the current file position.
304 /// For thread safe reads and writes see the following functions:
305 /// @see File::Read (void *, size_t, off_t &)
306 /// @see File::Write (const void *, size_t, off_t &)
308 /// @param[in] offset
309 /// The offset to seek to within the file relative to the
310 /// current file position.
312 /// @param[in] error_ptr
313 /// A pointer to a lldb_private::Error object that will be
314 /// filled in if non-NULL.
317 /// The resulting seek offset, or -1 on error.
318 //------------------------------------------------------------------
320 SeekFromCurrent (off_t offset, Error *error_ptr = NULL);
322 //------------------------------------------------------------------
323 /// Seek to an offset relative to the end of the file.
325 /// NOTE: This function is NOT thread safe, other threads that
326 /// access this object might also change the current file position.
327 /// For thread safe reads and writes see the following functions:
328 /// @see File::Read (void *, size_t, off_t &)
329 /// @see File::Write (const void *, size_t, off_t &)
331 /// @param[in/out] offset
332 /// The offset to seek to within the file relative to the
333 /// end of the file which gets filled in the the resulting
334 /// absolute file offset.
336 /// @param[in] error_ptr
337 /// A pointer to a lldb_private::Error object that will be
338 /// filled in if non-NULL.
341 /// The resulting seek offset, or -1 on error.
342 //------------------------------------------------------------------
344 SeekFromEnd (off_t offset, Error *error_ptr = NULL);
346 //------------------------------------------------------------------
347 /// Read bytes from a file from the specified file offset.
349 /// NOTE: This function is thread safe in that clients manager their
350 /// own file position markers and reads on other threads won't mess
351 /// up the current read.
354 /// A buffer where to put the bytes that are read.
356 /// @param[in/out] num_bytes
357 /// The number of bytes to read form the current file position
358 /// which gets modified with the number of bytes that were read.
360 /// @param[in/out] offset
361 /// The offset within the file from which to read \a num_bytes
362 /// bytes. This offset gets incremented by the number of bytes
366 /// An error object that indicates success or the reason for
368 //------------------------------------------------------------------
370 Read (void *dst, size_t &num_bytes, off_t &offset);
372 //------------------------------------------------------------------
373 /// Read bytes from a file from the specified file offset.
375 /// NOTE: This function is thread safe in that clients manager their
376 /// own file position markers and reads on other threads won't mess
377 /// up the current read.
379 /// @param[in/out] num_bytes
380 /// The number of bytes to read form the current file position
381 /// which gets modified with the number of bytes that were read.
383 /// @param[in/out] offset
384 /// The offset within the file from which to read \a num_bytes
385 /// bytes. This offset gets incremented by the number of bytes
388 /// @param[in] null_terminate
389 /// Ensure that the data that is read is terminated with a NULL
390 /// character so that the data can be used as a C string.
392 /// @param[out] data_buffer_sp
393 /// A data buffer to create and fill in that will contain any
394 /// data that is read from the file. This buffer will be reset
395 /// if an error occurs.
398 /// An error object that indicates success or the reason for
400 //------------------------------------------------------------------
402 Read (size_t &num_bytes,
405 lldb::DataBufferSP &data_buffer_sp);
407 //------------------------------------------------------------------
408 /// Write bytes to a file at the specified file offset.
410 /// NOTE: This function is thread safe in that clients manager their
411 /// own file position markers, though clients will need to implement
412 /// their own locking externally to avoid multiple people writing
413 /// to the file at the same time.
416 /// A buffer containing the bytes to write.
418 /// @param[in/out] num_bytes
419 /// The number of bytes to write to the file at offset \a offset.
420 /// \a num_bytes gets modified with the number of bytes that
423 /// @param[in/out] offset
424 /// The offset within the file at which to write \a num_bytes
425 /// bytes. This offset gets incremented by the number of bytes
426 /// that were written.
429 /// An error object that indicates success or the reason for
431 //------------------------------------------------------------------
433 Write (const void *src, size_t &num_bytes, off_t &offset);
435 //------------------------------------------------------------------
436 /// Flush the current stream
439 /// An error object that indicates success or the reason for
441 //------------------------------------------------------------------
445 //------------------------------------------------------------------
449 /// An error object that indicates success or the reason for
451 //------------------------------------------------------------------
455 //------------------------------------------------------------------
456 /// Output printf formatted output to the stream.
458 /// Print some formatted output to the stream.
460 /// @param[in] format
461 /// A printf style format string.
464 /// Variable arguments that are needed for the printf style
465 /// format string \a format.
466 //------------------------------------------------------------------
468 Printf (const char *format, ...) __attribute__ ((format (printf, 2, 3)));
471 PrintfVarArg(const char *format, va_list args);
477 DescriptorIsValid () const
479 return m_descriptor >= 0;
483 StreamIsValid () const
485 return m_stream != kInvalidStream;
488 //------------------------------------------------------------------
490 //------------------------------------------------------------------
497 } // namespace lldb_private
499 #endif // #if defined(__cplusplus)
500 #endif // liblldb_File_h_