File.h revision d35305ab31c10130fd60cec3f6ff62c49f1fb9dd 
1//===-- File.h --------------------------------------------------*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9
10#ifndef liblldb_File_h_
11#define liblldb_File_h_
12#if defined(__cplusplus)
13
14#include "lldb/lldb-private.h"
15
16namespace lldb_private {
17
18//----------------------------------------------------------------------
19/// @class File File.h "lldb/Host/File.h"
20/// @brief A file class.
21///
22/// A file class that divides abstracts the LLDB core from host file
23/// functionality.
24//----------------------------------------------------------------------
25class File
26{
27public:
28
29    enum OpenOptions
30    {
31        eOpenOptionRead                 = (1u << 0),    // Open file for reading
32        eOpenOptionWrite                = (1u << 1),    // Open file for writing
33        eOpenOptionAppend               = (1u << 2),    // Don't truncate file when opening, append to end of file
34        eOpenOptionNonBlocking          = (1u << 3),    // File reads
35        eOpenOptionCanCreate            = (1u << 4),    // Create file if doesn't already exist
36        eOpenOptionCanCreateNewOnly     = (1u << 5),    // Can create file only if it doesn't already exist
37        eOpenOptionTruncate             = (1u << 6),    // Truncate file when opening existing
38        eOpenOptionSharedLock           = (1u << 7),    // Open file and get shared lock
39        eOpenOptionExclusiveLock        = (1u << 8)     // Open file and get exclusive lock
40    };
41
42    enum Permissions
43    {
44        ePermissionsUserRead        = (1u << 0),
45        ePermissionsUserWrite       = (1u << 1),
46        ePermissionsUserExecute     = (1u << 2),
47        ePermissionsGroupRead       = (1u << 3),
48        ePermissionsGroupWrite      = (1u << 4),
49        ePermissionsGroupExecute    = (1u << 5),
50        ePermissionsWorldRead       = (1u << 6),
51        ePermissionsWorldWrite      = (1u << 7),
52        ePermissionsWorldExecute    = (1u << 8)
53    };
54
55    File() : m_file_desc (-1)
56    {
57    }
58
59    //------------------------------------------------------------------
60    /// Constructor with path.
61    ///
62    /// Takes a path to a file which can be just a filename, or a full
63    /// path. If \a path is not NULL or empty, this function will call
64    /// File::Open (const char *path, uint32_t options, uint32_t permissions).
65    ///
66    /// @param[in] path
67    ///     The full or partial path to a file.
68    ///
69    /// @param[in] options
70    ///     Options to use when opening (see File::OpenOptions)
71    ///
72    /// @param[in] permissions
73    ///     Options to use when opening (see File::Permissions)
74    ///
75    /// @see File::Open (const char *path, uint32_t options, uint32_t permissions)
76    //------------------------------------------------------------------
77    File (const char *path,
78          uint32_t options,
79          uint32_t permissions);
80
81    //------------------------------------------------------------------
82    /// Destructor.
83    ///
84    /// The destructor is virtual in case this class is subclassed.
85    //------------------------------------------------------------------
86    virtual
87    ~File ();
88
89    bool
90    IsValid () const
91    {
92        return m_file_desc >= 0;
93    }
94
95    //------------------------------------------------------------------
96    /// Convert to pointer operator.
97    ///
98    /// This allows code to check a File object to see if it
99    /// contains anything valid using code such as:
100    ///
101    /// @code
102    /// File file(...);
103    /// if (file)
104    /// { ...
105    /// @endcode
106    ///
107    /// @return
108    ///     A pointer to this object if either the directory or filename
109    ///     is valid, NULL otherwise.
110    //------------------------------------------------------------------
111    operator
112    bool () const
113    {
114        return m_file_desc >= 0;
115    }
116
117    //------------------------------------------------------------------
118    /// Logical NOT operator.
119    ///
120    /// This allows code to check a File object to see if it is
121    /// invalid using code such as:
122    ///
123    /// @code
124    /// File file(...);
125    /// if (!file)
126    /// { ...
127    /// @endcode
128    ///
129    /// @return
130    ///     Returns \b true if the object has an empty directory and
131    ///     filename, \b false otherwise.
132    //------------------------------------------------------------------
133    bool
134    operator! () const
135    {
136        return m_file_desc < 0;
137    }
138
139    //------------------------------------------------------------------
140    /// Get the file spec for this file.
141    ///
142    /// @return
143    ///     A reference to the file specification object.
144    //------------------------------------------------------------------
145    Error
146    GetFileSpec (FileSpec &file_spec) const;
147
148    //------------------------------------------------------------------
149    /// Open a file for read/writing with the specified options.
150    ///
151    /// Takes a path to a file which can be just a filename, or a full
152    /// path.
153    ///
154    /// @param[in] path
155    ///     The full or partial path to a file.
156    ///
157    /// @param[in] options
158    ///     Options to use when opening (see File::OpenOptions)
159    ///
160    /// @param[in] permissions
161    ///     Options to use when opening (see File::Permissions)
162    //------------------------------------------------------------------
163    Error
164    Open (const char *path,
165          uint32_t options,
166          uint32_t permissions);
167
168    Error
169    Close ();
170
171    //------------------------------------------------------------------
172    /// Read bytes from a file from the current file position.
173    ///
174    /// NOTE: This function is NOT thread safe. Use the read function
175    /// that takes an "off_t &offset" to ensure correct operation in
176    /// multi-threaded environments.
177    ///
178    /// @param[in] buf
179    ///     A buffer where to put the bytes that are read.
180    ///
181    /// @param[in/out] num_bytes
182    ///     The number of bytes to read form the current file position
183    ///     which gets modified with the number of bytes that were read.
184    ///
185    /// @return
186    ///     An error object that indicates success or the reason for
187    ///     failure.
188    //------------------------------------------------------------------
189    Error
190    Read (void *buf, size_t &num_bytes);
191
192    //------------------------------------------------------------------
193    /// Write bytes to a file at the current file position.
194    ///
195    /// NOTE: This function is NOT thread safe. Use the write function
196    /// that takes an "off_t &offset" to ensure correct operation in
197    /// multi-threaded environments.
198    ///
199    /// @param[in] buf
200    ///     A buffer where to put the bytes that are read.
201    ///
202    /// @param[in/out] num_bytes
203    ///     The number of bytes to write to the current file position
204    ///     which gets modified with the number of bytes that were
205    ///     written.
206    ///
207    /// @return
208    ///     An error object that indicates success or the reason for
209    ///     failure.
210    //------------------------------------------------------------------
211    Error
212    Write (const void *buf, size_t &num_bytes);
213
214    //------------------------------------------------------------------
215    /// Seek to an offset relative to the beginning of the file.
216    ///
217    /// NOTE: This function is NOT thread safe, other threads that
218    /// access this object might also change the current file position.
219    /// For thread safe reads and writes see the following functions:
220    /// @see File::Read (void *, size_t, off_t &)
221    /// @see File::Write (const void *, size_t, off_t &)
222    ///
223    /// @param[in/out] offset
224    ///     The offset to seek to within the file relative to the
225    ///     beginning of the file which gets filled in the the resulting
226    ///     absolute file offset.
227    ///
228    /// @return
229    ///     An error object that indicates success or the reason for
230    ///     failure.
231    //------------------------------------------------------------------
232    Error
233    SeekFromStart (off_t& offset);
234
235    //------------------------------------------------------------------
236    /// Seek to an offset relative to the current file position.
237    ///
238    /// NOTE: This function is NOT thread safe, other threads that
239    /// access this object might also change the current file position.
240    /// For thread safe reads and writes see the following functions:
241    /// @see File::Read (void *, size_t, off_t &)
242    /// @see File::Write (const void *, size_t, off_t &)
243    ///
244    /// @param[in/out] offset
245    ///     The offset to seek to within the file relative to the
246    ///     current file position. On return this parameter gets filled
247    ///     in the the resulting absolute file offset.
248    ///
249    /// @return
250    ///     An error object that indicates success or the reason for
251    ///     failure.
252    //------------------------------------------------------------------
253    Error
254    SeekFromCurrent (off_t& offset);
255
256    //------------------------------------------------------------------
257    /// Seek to an offset relative to the end of the file.
258    ///
259    /// NOTE: This function is NOT thread safe, other threads that
260    /// access this object might also change the current file position.
261    /// For thread safe reads and writes see the following functions:
262    /// @see File::Read (void *, size_t, off_t &)
263    /// @see File::Write (const void *, size_t, off_t &)
264    ///
265    /// @param[in/out] offset
266    ///     The offset to seek to within the file relative to the
267    ///     end of the file which gets filled in the the resulting
268    ///     absolute file offset.
269    ///
270    /// @return
271    ///     An error object that indicates success or the reason for
272    ///     failure.
273    //------------------------------------------------------------------
274    Error
275    SeekFromEnd (off_t& offset);
276
277    //------------------------------------------------------------------
278    /// Read bytes from a file from the specified file offset.
279    ///
280    /// NOTE: This function is thread safe in that clients manager their
281    /// own file position markers and reads on other threads won't mess
282    /// up the current read.
283    ///
284    /// @param[in] buf
285    ///     A buffer where to put the bytes that are read.
286    ///
287    /// @param[in/out] num_bytes
288    ///     The number of bytes to read form the current file position
289    ///     which gets modified with the number of bytes that were read.
290    ///
291    /// @param[in/out] offset
292    ///     The offset within the file from which to read \a num_bytes
293    ///     bytes. This offset gets incremented by the number of bytes
294    ///     that were read.
295    ///
296    /// @return
297    ///     An error object that indicates success or the reason for
298    ///     failure.
299    //------------------------------------------------------------------
300    Error
301    Read (void *dst, size_t &num_bytes, off_t &offset);
302
303    //------------------------------------------------------------------
304    /// Write bytes to a file at the specified file offset.
305    ///
306    /// NOTE: This function is thread safe in that clients manager their
307    /// own file position markers, though clients will need to implement
308    /// their own locking externally to avoid multiple people writing
309    /// to the file at the same time.
310    ///
311    /// @param[in] buf
312    ///     A buffer containing the bytes to write.
313    ///
314    /// @param[in/out] num_bytes
315    ///     The number of bytes to write to the file at offset \a offset.
316    ///     \a num_bytes gets modified with the number of bytes that
317    ///     were read.
318    ///
319    /// @param[in/out] offset
320    ///     The offset within the file at which to write \a num_bytes
321    ///     bytes. This offset gets incremented by the number of bytes
322    ///     that were written.
323    ///
324    /// @return
325    ///     An error object that indicates success or the reason for
326    ///     failure.
327    //------------------------------------------------------------------
328    Error
329    Write (const void *src, size_t &num_bytes, off_t &offset);
330
331
332    //------------------------------------------------------------------
333    /// Sync to disk.
334    ///
335    /// @return
336    ///     An error object that indicates success or the reason for
337    ///     failure.
338    //------------------------------------------------------------------
339    Error
340    Sync ();
341
342protected:
343    //------------------------------------------------------------------
344    // Member variables
345    //------------------------------------------------------------------
346    int m_file_desc; ///< The open file handle or NULL if the file isn't opened
347};
348
349} // namespace lldb_private
350
351#endif  // #if defined(__cplusplus)
352#endif  // liblldb_File_h_
353