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 <sys/types.h>
18 #include "lldb/lldb-private.h"
20 namespace lldb_private {
22 //----------------------------------------------------------------------
23 /// @class File File.h "lldb/Host/File.h"
24 /// @brief A file class.
26 /// A file class that divides abstracts the LLDB core from host file
28 //----------------------------------------------------------------------
32 static int kInvalidDescriptor;
33 static FILE * kInvalidStream;
37 eOpenOptionRead = (1u << 0), // Open file for reading
38 eOpenOptionWrite = (1u << 1), // Open file for writing
39 eOpenOptionAppend = (1u << 2), // Don't truncate file when opening, append to end of file
40 eOpenOptionTruncate = (1u << 3), // Truncate file when opening
41 eOpenOptionNonBlocking = (1u << 4), // File reads
42 eOpenOptionCanCreate = (1u << 5), // Create file if doesn't already exist
43 eOpenOptionCanCreateNewOnly = (1u << 6), // Can create file only if it doesn't already exist
44 eOpenoptionDontFollowSymlinks = (1u << 7)
48 ConvertOpenOptionsForPOSIXOpen (uint32_t open_options);
51 m_descriptor (kInvalidDescriptor),
52 m_stream (kInvalidStream),
55 m_own_descriptor (false),
56 m_is_interactive (eLazyBoolCalculate),
57 m_is_real_terminal (eLazyBoolCalculate)
61 File (FILE *fh, bool transfer_ownership) :
62 m_descriptor (kInvalidDescriptor),
65 m_own_stream (transfer_ownership),
66 m_own_descriptor (false),
67 m_is_interactive (eLazyBoolCalculate),
68 m_is_real_terminal (eLazyBoolCalculate)
72 File (const File &rhs);
75 operator= (const File &rhs);
76 //------------------------------------------------------------------
77 /// Constructor with path.
79 /// Takes a path to a file which can be just a filename, or a full
80 /// path. If \a path is not NULL or empty, this function will call
81 /// File::Open (const char *path, uint32_t options, uint32_t permissions).
84 /// The full or partial path to a file.
86 /// @param[in] options
87 /// Options to use when opening (see File::OpenOptions)
89 /// @param[in] permissions
90 /// Options to use when opening (see File::Permissions)
92 /// @see File::Open (const char *path, uint32_t options, uint32_t permissions)
93 //------------------------------------------------------------------
94 File (const char *path,
96 uint32_t permissions = lldb::eFilePermissionsFileDefault);
98 //------------------------------------------------------------------
99 /// Constructor with FileSpec.
101 /// Takes a FileSpec pointing 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 FileSpec for this 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 FileSpec& filespec,
118 uint32_t permissions = lldb::eFilePermissionsFileDefault);
120 File (int fd, bool transfer_ownership) :
122 m_stream (kInvalidStream),
124 m_own_stream (false),
125 m_own_descriptor (transfer_ownership)
129 //------------------------------------------------------------------
132 /// The destructor is virtual in case this class is subclassed.
133 //------------------------------------------------------------------
140 return DescriptorIsValid() || StreamIsValid();
143 //------------------------------------------------------------------
144 /// Convert to pointer operator.
146 /// This allows code to check a File object to see if it
147 /// contains anything valid using code such as:
156 /// A pointer to this object if either the directory or filename
157 /// is valid, NULL otherwise.
158 //------------------------------------------------------------------
162 return DescriptorIsValid() || StreamIsValid();
165 //------------------------------------------------------------------
166 /// Logical NOT operator.
168 /// This allows code to check a File object to see if it is
169 /// invalid using code such as:
178 /// Returns \b true if the object has an empty directory and
179 /// filename, \b false otherwise.
180 //------------------------------------------------------------------
184 return !DescriptorIsValid() && !StreamIsValid();
187 //------------------------------------------------------------------
188 /// Get the file spec for this file.
191 /// A reference to the file specification object.
192 //------------------------------------------------------------------
194 GetFileSpec (FileSpec &file_spec) const;
196 //------------------------------------------------------------------
197 /// Open a file for read/writing with the specified options.
199 /// Takes a path to a file which can be just a filename, or a full
203 /// The full or partial path to a file.
205 /// @param[in] options
206 /// Options to use when opening (see File::OpenOptions)
208 /// @param[in] permissions
209 /// Options to use when opening (see File::Permissions)
210 //------------------------------------------------------------------
212 Open (const char *path,
214 uint32_t permissions = lldb::eFilePermissionsFileDefault);
220 Duplicate (const File &rhs);
223 GetDescriptor() const;
226 SetDescriptor(int fd, bool transfer_ownership);
232 SetStream (FILE *fh, bool transfer_ownership);
234 //------------------------------------------------------------------
235 /// Read bytes from a file from the current file position.
237 /// NOTE: This function is NOT thread safe. Use the read function
238 /// that takes an "off_t &offset" to ensure correct operation in
239 /// multi-threaded environments.
242 /// A buffer where to put the bytes that are read.
244 /// @param[in/out] num_bytes
245 /// The number of bytes to read form the current file position
246 /// which gets modified with the number of bytes that were read.
249 /// An error object that indicates success or the reason for
251 //------------------------------------------------------------------
253 Read (void *buf, size_t &num_bytes);
255 //------------------------------------------------------------------
256 /// Write bytes to a file at the current file position.
258 /// NOTE: This function is NOT thread safe. Use the write function
259 /// that takes an "off_t &offset" to ensure correct operation in
260 /// multi-threaded environments.
263 /// A buffer where to put the bytes that are read.
265 /// @param[in/out] num_bytes
266 /// The number of bytes to write to the current file position
267 /// which gets modified with the number of bytes that were
271 /// An error object that indicates success or the reason for
273 //------------------------------------------------------------------
275 Write (const void *buf, size_t &num_bytes);
277 //------------------------------------------------------------------
278 /// Seek to an offset relative to the beginning of the file.
280 /// NOTE: This function is NOT thread safe, other threads that
281 /// access this object might also change the current file position.
282 /// For thread safe reads and writes see the following functions:
283 /// @see File::Read (void *, size_t, off_t &)
284 /// @see File::Write (const void *, size_t, off_t &)
286 /// @param[in] offset
287 /// The offset to seek to within the file relative to the
288 /// beginning of the file.
290 /// @param[in] error_ptr
291 /// A pointer to a lldb_private::Error object that will be
292 /// filled in if non-NULL.
295 /// The resulting seek offset, or -1 on error.
296 //------------------------------------------------------------------
298 SeekFromStart (off_t offset, Error *error_ptr = NULL);
300 //------------------------------------------------------------------
301 /// Seek to an offset relative to the current file position.
303 /// NOTE: This function is NOT thread safe, other threads that
304 /// access this object might also change the current file position.
305 /// For thread safe reads and writes see the following functions:
306 /// @see File::Read (void *, size_t, off_t &)
307 /// @see File::Write (const void *, size_t, off_t &)
309 /// @param[in] offset
310 /// The offset to seek to within the file relative to the
311 /// current file position.
313 /// @param[in] error_ptr
314 /// A pointer to a lldb_private::Error object that will be
315 /// filled in if non-NULL.
318 /// The resulting seek offset, or -1 on error.
319 //------------------------------------------------------------------
321 SeekFromCurrent (off_t offset, Error *error_ptr = NULL);
323 //------------------------------------------------------------------
324 /// Seek to an offset relative to the end of the file.
326 /// NOTE: This function is NOT thread safe, other threads that
327 /// access this object might also change the current file position.
328 /// For thread safe reads and writes see the following functions:
329 /// @see File::Read (void *, size_t, off_t &)
330 /// @see File::Write (const void *, size_t, off_t &)
332 /// @param[in/out] offset
333 /// The offset to seek to within the file relative to the
334 /// end of the file which gets filled in the the resulting
335 /// absolute file offset.
337 /// @param[in] error_ptr
338 /// A pointer to a lldb_private::Error object that will be
339 /// filled in if non-NULL.
342 /// The resulting seek offset, or -1 on error.
343 //------------------------------------------------------------------
345 SeekFromEnd (off_t offset, Error *error_ptr = NULL);
347 //------------------------------------------------------------------
348 /// Read bytes from a file from the specified file offset.
350 /// NOTE: This function is thread safe in that clients manager their
351 /// own file position markers and reads on other threads won't mess
352 /// up the current read.
355 /// A buffer where to put the bytes that are read.
357 /// @param[in/out] num_bytes
358 /// The number of bytes to read form the current file position
359 /// which gets modified with the number of bytes that were read.
361 /// @param[in/out] offset
362 /// The offset within the file from which to read \a num_bytes
363 /// bytes. This offset gets incremented by the number of bytes
367 /// An error object that indicates success or the reason for
369 //------------------------------------------------------------------
371 Read (void *dst, size_t &num_bytes, off_t &offset);
373 //------------------------------------------------------------------
374 /// Read bytes from a file from the specified file offset.
376 /// NOTE: This function is thread safe in that clients manager their
377 /// own file position markers and reads on other threads won't mess
378 /// up the current read.
380 /// @param[in/out] num_bytes
381 /// The number of bytes to read form the current file position
382 /// which gets modified with the number of bytes that were read.
384 /// @param[in/out] offset
385 /// The offset within the file from which to read \a num_bytes
386 /// bytes. This offset gets incremented by the number of bytes
389 /// @param[in] null_terminate
390 /// Ensure that the data that is read is terminated with a NULL
391 /// character so that the data can be used as a C string.
393 /// @param[out] data_buffer_sp
394 /// A data buffer to create and fill in that will contain any
395 /// data that is read from the file. This buffer will be reset
396 /// if an error occurs.
399 /// An error object that indicates success or the reason for
401 //------------------------------------------------------------------
403 Read (size_t &num_bytes,
406 lldb::DataBufferSP &data_buffer_sp);
408 //------------------------------------------------------------------
409 /// Write bytes to a file at the specified file offset.
411 /// NOTE: This function is thread safe in that clients manager their
412 /// own file position markers, though clients will need to implement
413 /// their own locking externally to avoid multiple people writing
414 /// to the file at the same time.
417 /// A buffer containing the bytes to write.
419 /// @param[in/out] num_bytes
420 /// The number of bytes to write to the file at offset \a offset.
421 /// \a num_bytes gets modified with the number of bytes that
424 /// @param[in/out] offset
425 /// The offset within the file at which to write \a num_bytes
426 /// bytes. This offset gets incremented by the number of bytes
427 /// that were written.
430 /// An error object that indicates success or the reason for
432 //------------------------------------------------------------------
434 Write (const void *src, size_t &num_bytes, off_t &offset);
436 //------------------------------------------------------------------
437 /// Flush the current stream
440 /// An error object that indicates success or the reason for
442 //------------------------------------------------------------------
446 //------------------------------------------------------------------
450 /// An error object that indicates success or the reason for
452 //------------------------------------------------------------------
456 //------------------------------------------------------------------
457 /// Get the permissions for a this file.
460 /// Bits logical OR'ed together from the permission bits defined
461 /// in lldb_private::File::Permissions.
462 //------------------------------------------------------------------
464 GetPermissions(Error &error) const;
467 GetPermissions (const char *path, Error &error);
470 //------------------------------------------------------------------
471 /// Return true if this file is interactive.
474 /// True if this file is a terminal (tty or pty), false
476 //------------------------------------------------------------------
480 //------------------------------------------------------------------
481 /// Return true if this file from a real terminal.
483 /// Just knowing a file is a interactive isn't enough, we also need
484 /// to know if the terminal has a width and height so we can do
485 /// cursor movement and other terminal maninpulations by sending
486 /// escape sequences.
489 /// True if this file is a terminal (tty, not a pty) that has
490 /// a non-zero width and height, false otherwise.
491 //------------------------------------------------------------------
493 GetIsRealTerminal ();
495 //------------------------------------------------------------------
496 /// Output printf formatted output to the stream.
498 /// Print some formatted output to the stream.
500 /// @param[in] format
501 /// A printf style format string.
504 /// Variable arguments that are needed for the printf style
505 /// format string \a format.
506 //------------------------------------------------------------------
508 Printf (const char *format, ...) __attribute__ ((format (printf, 2, 3)));
511 PrintfVarArg(const char *format, va_list args);
515 SetOptions (uint32_t options)
523 DescriptorIsValid () const
525 return m_descriptor >= 0;
529 StreamIsValid () const
531 return m_stream != kInvalidStream;
535 CalculateInteractiveAndTerminal ();
537 //------------------------------------------------------------------
539 //------------------------------------------------------------------
544 bool m_own_descriptor;
545 LazyBool m_is_interactive;
546 LazyBool m_is_real_terminal;
549 } // namespace lldb_private
551 #endif // #if defined(__cplusplus)
552 #endif // liblldb_File_h_