WPILibC++ 2024.3.2
os.h
Go to the documentation of this file.
1// Formatting library for C++ - optional OS-specific functionality
2//
3// Copyright (c) 2012 - present, Victor Zverovich
4// All rights reserved.
5//
6// For the license information refer to format.h.
7
8#ifndef FMT_OS_H_
9#define FMT_OS_H_
10
11#include <cerrno>
12#include <cstddef>
13#include <cstdio>
14#include <system_error> // std::system_error
15
16#if defined __APPLE__ || defined(__FreeBSD__)
17# include <xlocale.h> // for LC_NUMERIC_MASK on OS X
18#endif
19
20#include "format.h"
21
22#ifndef FMT_USE_FCNTL
23// UWP doesn't provide _pipe.
24# if FMT_HAS_INCLUDE("winapifamily.h")
25# include <winapifamily.h>
26# endif
27# if (FMT_HAS_INCLUDE(<fcntl.h>) || defined(__APPLE__) || \
28 defined(__linux__)) && \
29 (!defined(WINAPI_FAMILY) || \
30 (WINAPI_FAMILY == WINAPI_FAMILY_DESKTOP_APP))
31# include <fcntl.h> // for O_RDONLY
32# define FMT_USE_FCNTL 1
33# else
34# define FMT_USE_FCNTL 0
35# endif
36#endif
37
38#ifndef FMT_POSIX
39# if defined(_WIN32) && !defined(__MINGW32__)
40// Fix warnings about deprecated symbols.
41# define FMT_POSIX(call) _##call
42# else
43# define FMT_POSIX(call) call
44# endif
45#endif
46
47// Calls to system functions are wrapped in FMT_SYSTEM for testability.
48#ifdef FMT_SYSTEM
49# define FMT_POSIX_CALL(call) FMT_SYSTEM(call)
50#else
51# define FMT_SYSTEM(call) ::call
52# ifdef _WIN32
53// Fix warnings about deprecated symbols.
54# define FMT_POSIX_CALL(call) ::_##call
55# else
56# define FMT_POSIX_CALL(call) ::call
57# endif
58#endif
59
60// Retries the expression while it evaluates to error_result and errno
61// equals to EINTR.
62#ifndef _WIN32
63# define FMT_RETRY_VAL(result, expression, error_result) \
64 do { \
65 (result) = (expression); \
66 } while ((result) == (error_result) && errno == EINTR)
67#else
68# define FMT_RETRY_VAL(result, expression, error_result) result = (expression)
69#endif
70
71#define FMT_RETRY(result, expression) FMT_RETRY_VAL(result, expression, -1)
72
75
76/**
77 \rst
78 A reference to a null-terminated string. It can be constructed from a C
79 string or ``std::string``.
80
81 You can use one of the following type aliases for common character types:
82
83 +---------------+-----------------------------+
84 | Type | Definition |
85 +===============+=============================+
86 | cstring_view | basic_cstring_view<char> |
87 +---------------+-----------------------------+
88 | wcstring_view | basic_cstring_view<wchar_t> |
89 +---------------+-----------------------------+
90
91 This class is most useful as a parameter type to allow passing
92 different types of strings to a function, for example::
93
94 template <typename... Args>
95 std::string format(cstring_view format_str, const Args & ... args);
96
97 format("{}", 42);
98 format(std::string("{}"), 42);
99 \endrst
100 */
101template <typename Char> class basic_cstring_view {
102 private:
103 const Char* data_;
104
105 public:
106 /** Constructs a string reference object from a C string. */
107 basic_cstring_view(const Char* s) : data_(s) {}
108
109 /**
110 \rst
111 Constructs a string reference from an ``std::string`` object.
112 \endrst
113 */
114 basic_cstring_view(const std::basic_string<Char>& s) : data_(s.c_str()) {}
115
116 /** Returns the pointer to a C string. */
117 const Char* c_str() const { return data_; }
118};
119
122
123#ifdef _WIN32
124FMT_API const std::error_category& system_category() noexcept;
125
126namespace detail {
127FMT_API void format_windows_error(buffer<char>& out, int error_code,
128 const char* message) noexcept;
129}
130
131FMT_API std::system_error vwindows_error(int error_code, string_view format_str,
132 format_args args);
133
134/**
135 \rst
136 Constructs a :class:`std::system_error` object with the description
137 of the form
138
139 .. parsed-literal::
140 *<message>*: *<system-message>*
141
142 where *<message>* is the formatted message and *<system-message>* is the
143 system message corresponding to the error code.
144 *error_code* is a Windows error code as given by ``GetLastError``.
145 If *error_code* is not a valid error code such as -1, the system message
146 will look like "error -1".
147
148 **Example**::
149
150 // This throws a system_error with the description
151 // cannot open file 'madeup': The system cannot find the file specified.
152 // or similar (system message may vary).
153 const char *filename = "madeup";
154 LPOFSTRUCT of = LPOFSTRUCT();
155 HFILE file = OpenFile(filename, &of, OF_READ);
156 if (file == HFILE_ERROR) {
157 throw fmt::windows_error(GetLastError(),
158 "cannot open file '{}'", filename);
159 }
160 \endrst
161*/
162template <typename... Args>
163std::system_error windows_error(int error_code, string_view message,
164 const Args&... args) {
165 return vwindows_error(error_code, message, fmt::make_format_args(args...));
166}
167
168// Reports a Windows error without throwing an exception.
169// Can be used to report errors from destructors.
170FMT_API void report_windows_error(int error_code, const char* message) noexcept;
171#else
172inline const std::error_category& system_category() noexcept {
173 return std::system_category();
174}
175#endif // _WIN32
176
177// std::system is not available on some platforms such as iOS (#2248).
178#ifdef __OSX__
179template <typename S, typename... Args, typename Char = char_t<S>>
180void say(const S& format_str, Args&&... args) {
181 std::system(format("say \"{}\"", format(format_str, args...)).c_str());
182}
183#endif
184
185// A buffered file.
187 private:
188 FILE* file_;
189
190 friend class file;
191
192 explicit buffered_file(FILE* f) : file_(f) {}
193
194 public:
195 buffered_file(const buffered_file&) = delete;
196 void operator=(const buffered_file&) = delete;
197
198 // Constructs a buffered_file object which doesn't represent any file.
199 buffered_file() noexcept : file_(nullptr) {}
200
201 // Destroys the object closing the file it represents if any.
203
204 public:
205 buffered_file(buffered_file&& other) noexcept : file_(other.file_) {
206 other.file_ = nullptr;
207 }
208
210 close();
211 file_ = other.file_;
212 other.file_ = nullptr;
213 return *this;
214 }
215
216 // Opens a file.
218
219 // Closes the file.
221
222 // Returns the pointer to a FILE object representing this file.
223 FILE* get() const noexcept { return file_; }
224
225 FMT_API int descriptor() const;
226
227 void vprint(string_view format_str, format_args args) {
228 fmt::vprint(file_, format_str, args);
229 }
230
231 template <typename... Args>
232 inline void print(string_view format_str, const Args&... args) {
233 vprint(format_str, fmt::make_format_args(args...));
234 }
235};
236
237#if FMT_USE_FCNTL
238// A file. Closed file is represented by a file object with descriptor -1.
239// Methods that are not declared with noexcept may throw
240// fmt::system_error in case of failure. Note that some errors such as
241// closing the file multiple times will cause a crash on Windows rather
242// than an exception. You can get standard behavior by overriding the
243// invalid parameter handler with _set_invalid_parameter_handler.
244class FMT_API file {
245 private:
246 int fd_; // File descriptor.
247
248 // Constructs a file object with a given descriptor.
249 explicit file(int fd) : fd_(fd) {}
250
251 public:
252 // Possible values for the oflag argument to the constructor.
253 enum {
254 RDONLY = FMT_POSIX(O_RDONLY), // Open for reading only.
255 WRONLY = FMT_POSIX(O_WRONLY), // Open for writing only.
256 RDWR = FMT_POSIX(O_RDWR), // Open for reading and writing.
257 CREATE = FMT_POSIX(O_CREAT), // Create if the file doesn't exist.
258 APPEND = FMT_POSIX(O_APPEND), // Open in append mode.
259 TRUNC = FMT_POSIX(O_TRUNC) // Truncate the content of the file.
260 };
261
262 // Constructs a file object which doesn't represent any file.
263 file() noexcept : fd_(-1) {}
264
265 // Opens a file and constructs a file object representing this file.
266 file(cstring_view path, int oflag);
267
268 public:
269 file(const file&) = delete;
270 void operator=(const file&) = delete;
271
272 file(file&& other) noexcept : fd_(other.fd_) { other.fd_ = -1; }
273
274 // Move assignment is not noexcept because close may throw.
275 file& operator=(file&& other) {
276 close();
277 fd_ = other.fd_;
278 other.fd_ = -1;
279 return *this;
280 }
281
282 // Destroys the object closing the file it represents if any.
283 ~file() noexcept;
284
285 // Returns the file descriptor.
286 int descriptor() const noexcept { return fd_; }
287
288 // Closes the file.
289 void close();
290
291 // Returns the file size. The size has signed type for consistency with
292 // stat::st_size.
293 long long size() const;
294
295 // Attempts to read count bytes from the file into the specified buffer.
296 size_t read(void* buffer, size_t count);
297
298 // Attempts to write count bytes from the specified buffer to the file.
299 size_t write(const void* buffer, size_t count);
300
301 // Duplicates a file descriptor with the dup function and returns
302 // the duplicate as a file object.
303 static file dup(int fd);
304
305 // Makes fd be the copy of this file descriptor, closing fd first if
306 // necessary.
307 void dup2(int fd);
308
309 // Makes fd be the copy of this file descriptor, closing fd first if
310 // necessary.
311 void dup2(int fd, std::error_code& ec) noexcept;
312
313 // Creates a pipe setting up read_end and write_end file objects for reading
314 // and writing respectively.
315 static void pipe(file& read_end, file& write_end);
316
317 // Creates a buffered_file object associated with this file and detaches
318 // this file object from the file.
319 buffered_file fdopen(const char* mode);
320
321# if defined(_WIN32) && !defined(__MINGW32__)
322 // Opens a file and constructs a file object representing this file by
323 // wcstring_view filename. Windows only.
324 static file open_windows_file(wcstring_view path, int oflag);
325# endif
326};
327
328// Returns the memory page size.
329long getpagesize();
330
331namespace detail {
332
333struct buffer_size {
334 buffer_size() = default;
335 size_t value = 0;
336 buffer_size operator=(size_t val) const {
337 auto bs = buffer_size();
338 bs.value = val;
339 return bs;
340 }
341};
342
343struct ostream_params {
344 int oflag = file::WRONLY | file::CREATE | file::TRUNC;
345 size_t buffer_size = BUFSIZ > 32768 ? BUFSIZ : 32768;
346
347 ostream_params() {}
348
349 template <typename... T>
350 ostream_params(T... params, int new_oflag) : ostream_params(params...) {
351 oflag = new_oflag;
352 }
353
354 template <typename... T>
355 ostream_params(T... params, detail::buffer_size bs)
356 : ostream_params(params...) {
357 this->buffer_size = bs.value;
358 }
359
360// Intel has a bug that results in failure to deduce a constructor
361// for empty parameter packs.
362# if defined(__INTEL_COMPILER) && __INTEL_COMPILER < 2000
363 ostream_params(int new_oflag) : oflag(new_oflag) {}
364 ostream_params(detail::buffer_size bs) : buffer_size(bs.value) {}
365# endif
366};
367
368class file_buffer final : public buffer<char> {
369 file file_;
370
371 FMT_API void grow(size_t) override;
372
373 public:
374 FMT_API file_buffer(cstring_view path, const ostream_params& params);
375 FMT_API file_buffer(file_buffer&& other);
376 FMT_API ~file_buffer();
377
378 void flush() {
379 if (size() == 0) return;
380 file_.write(data(), size() * sizeof(data()[0]));
381 clear();
382 }
383
384 void close() {
385 flush();
386 file_.close();
387 }
388};
389
390} // namespace detail
391
392// Added {} below to work around default constructor error known to
393// occur in Xcode versions 7.2.1 and 8.2.1.
394constexpr detail::buffer_size buffer_size{};
395
396/** A fast output stream which is not thread-safe. */
397class FMT_API ostream {
398 private:
399 FMT_MSC_WARNING(suppress : 4251)
400 detail::file_buffer buffer_;
401
402 ostream(cstring_view path, const detail::ostream_params& params)
403 : buffer_(path, params) {}
404
405 public:
406 ostream(ostream&& other) : buffer_(std::move(other.buffer_)) {}
407
408 ~ostream();
409
410 void flush() { buffer_.flush(); }
411
412 template <typename... T>
413 friend ostream output_file(cstring_view path, T... params);
414
415 void close() { buffer_.close(); }
416
417 /**
418 Formats ``args`` according to specifications in ``fmt`` and writes the
419 output to the file.
420 */
421 template <typename... T> void print(format_string<T...> fmt, T&&... args) {
423 fmt::make_format_args(args...));
424 }
425};
426
427/**
428 \rst
429 Opens a file for writing. Supported parameters passed in *params*:
430
431 * ``<integer>``: Flags passed to `open
432 <https://pubs.opengroup.org/onlinepubs/007904875/functions/open.html>`_
433 (``file::WRONLY | file::CREATE | file::TRUNC`` by default)
434 * ``buffer_size=<integer>``: Output buffer size
435
436 **Example**::
437
438 auto out = fmt::output_file("guide.txt");
439 out.print("Don't {}", "Panic");
440 \endrst
441 */
442template <typename... T>
443inline ostream output_file(cstring_view path, T... params) {
444 return {path, detail::ostream_params(params...)};
445}
446#endif // FMT_USE_FCNTL
447
450
451#endif // FMT_OS_H_
then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file
Definition: ThirdPartyNotices.txt:192
\rst A reference to a null-terminated string.
Definition: os.h:101
basic_cstring_view(const std::basic_string< Char > &s)
\rst Constructs a string reference from an std::string object.
Definition: os.h:114
basic_cstring_view(const Char *s)
Constructs a string reference object from a C string.
Definition: os.h:107
const Char * c_str() const
Returns the pointer to a C string.
Definition: os.h:117
\rst A view of a collection of formatting arguments.
Definition: core.h:1857
A compile-time format string.
Definition: core.h:2721
Definition: os.h:186
void vprint(string_view format_str, format_args args)
Definition: os.h:227
void operator=(const buffered_file &)=delete
FMT_API void close()
FMT_API int descriptor() const
FMT_API ~buffered_file() noexcept
friend class file
Definition: os.h:190
FILE * get() const noexcept
Definition: os.h:223
buffered_file() noexcept
Definition: os.h:199
FMT_API buffered_file(cstring_view filename, cstring_view mode)
buffered_file(const buffered_file &)=delete
void print(string_view format_str, const Args &... args)
Definition: os.h:232
buffered_file & operator=(buffered_file &&other)
Definition: os.h:209
#define FMT_END_EXPORT
Definition: core.h:185
typename detail::char_t_impl< S >::type char_t
String's character type.
Definition: core.h:646
#define FMT_BEGIN_NAMESPACE
Definition: core.h:174
#define FMT_API
Definition: core.h:202
constexpr auto make_format_args(T &... args) -> format_arg_store< Context, remove_cvref_t< T >... >
\rst Constructs a ~fmtformat_arg_store object that contains references to arguments and can be implic...
Definition: core.h:1824
#define FMT_BEGIN_EXPORT
Definition: core.h:184
#define FMT_MSC_WARNING(...)
Definition: core.h:58
#define FMT_END_NAMESPACE
Definition: core.h:177
auto system_error(int error_code, format_string< T... > fmt, T &&... args) -> std::system_error
\rst Constructs :class:std::system_error with a message formatted with fmt::format(fmt,...
Definition: format.h:3972
void print(wpi::raw_ostream &os, const S &format_str, Args &&... args)
Prints formatted data to the stream os.
Definition: raw_ostream.h:25
FMT_BEGIN_NAMESPACE void vprint(wpi::raw_ostream &os, string_view format_str, fmt::format_args args)
Definition: raw_ostream.h:14
detail namespace with internal helper functions
Definition: xchar.h:20
auto write(OutputIt out, const std::tm &time, const std::locale &loc, char format, char modifier=0) -> OutputIt
Definition: chrono.h:419
@ value
the parser finished reading a JSON value
constexpr auto count() -> size_t
Definition: core.h:1203
conditional_t< std::is_same< T, char >::value, appender, std::back_insert_iterator< buffer< T > > > buffer_appender
Definition: core.h:1113
Definition: array.h:89
value_type read(const void *memory, endianness endian)
Read a value of a particular endianness from memory.
Definition: Endian.h:65
#define FMT_POSIX(call)
Definition: os.h:43
const std::error_category & system_category() noexcept
Definition: os.h:172
#define S(label, offset, message)
Definition: Errors.h:119
auto format(wformat_string< T... > fmt, T &&... args) -> std::wstring
Definition: xchar.h:108
auto vformat_to(OutputIt out, const S &format_str, basic_format_args< buffer_context< type_identity_t< Char > > > args) -> OutputIt
Definition: xchar.h:144