MySQL 9.0.0
Source Code Documentation
utils.h
Go to the documentation of this file.
1/*
2 Copyright (c) 2015, 2024, Oracle and/or its affiliates.
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License, version 2.0,
6 as published by the Free Software Foundation.
7
8 This program is designed to work with certain software (including
9 but not limited to OpenSSL) that is licensed under separate terms,
10 as designated in a particular file or component or in included license
11 documentation. The authors of MySQL hereby grant you an additional
12 permission to link the program and your derivative works with the
13 separately licensed software that they have either included with
14 the program or referenced in the documentation.
15
16 This program is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 GNU General Public License for more details.
20
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, write to the Free Software
23 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
24*/
25
26#ifndef MYSQLROUTER_UTILS_INCLUDED
27#define MYSQLROUTER_UTILS_INCLUDED
28
30
31#include <sys/stat.h> // mode_t
32
33#include <chrono>
34#include <cstdint>
35#include <functional>
36#include <sstream>
37#include <string>
38
39#include "my_compiler.h" // MY_ATTRIBUTE
40
42
43#ifdef _WIN32
44extern "C" {
45extern bool ROUTER_UTILS_EXPORT g_windows_service;
46}
47#endif
48
49namespace mysqlrouter {
50
51#ifndef _WIN32
52using perm_mode = mode_t;
53#else
54using perm_mode = int;
55#endif
56/** @brief Constant for directory accessible only for the owner */
58
59// Some (older) compiler have no std::to_string available
60template <typename T>
61std::string to_string(const T &data) {
63 os << data;
64 return os.str();
65}
66
67// represent milliseconds as floating point seconds
68std::string ROUTER_UTILS_EXPORT
69ms_to_seconds_string(const std::chrono::milliseconds &msec);
70
71/**
72 * Validates a string containing a TCP port
73 *
74 * Validates whether the data can be used as a TCP port. A TCP port is
75 * a valid number in the range of 0 and 65535. The returned integer is
76 * of type uint16_t.
77 *
78 * An empty data string will result in TCP port 0 to be returned.
79 *
80 * Throws runtime_error when the given string can not be converted
81 * to an integer or when the integer is to big.
82 *
83 * @param data string containing the TCP port number
84 * @return uint16_t the TCP port number
85 */
86uint16_t ROUTER_UTILS_EXPORT get_tcp_port(const std::string &data);
87
88/** @brief Dumps buffer as hex values
89 *
90 * Debugging function which dumps the given buffer as hex values
91 * in rows of 16 bytes. When literals is true, characters in a-z
92 * or A-Z, are printed as-is.
93 *
94 * @param buffer char array or front of vector<uint8_t>
95 * @param count number of bytes to dump
96 * @return string containing the dump
97 */
98std::string hexdump(const unsigned char *buffer, size_t count);
99
100/** @brief Prompts for a password from the console.
101 */
102std::string ROUTER_UTILS_EXPORT prompt_password(const std::string &prompt);
103
104/** @brief Override default prompt password function
105 */
107set_prompt_password(const std::function<std::string(const std::string &)> &f);
108
109#ifdef _WIN32
110/** @brief Returns whether if the router process is running as a Windows Service
111 */
112bool ROUTER_UTILS_EXPORT is_running_as_service();
113
114/** @brief Writes to the Windows event log.
115 *
116 * @param msg Message to log
117 *
118 * @throws std::runtime_error in case of an error
119 */
120void ROUTER_UTILS_EXPORT write_windows_event_log(const std::string &msg);
121
122#endif
123
124/** @brief Substitutes placeholders of environment variables in a string
125 *
126 * Substitutes placeholders of environment variables in a string. A
127 * placeholder contains the name of the variable and will be fetched
128 * from the environment. The substitution is done in-place.
129 *
130 * Note that it is not an error to pass a string with no variable to
131 * be substituted - in such case success will be returned, and the
132 * original string will remain unchanged.
133 * Also note, that if an error occurs, the resulting string value is
134 * undefined (it will be left in an inconsistent state).
135 *
136 * @return bool (success flag)
137 */
138bool ROUTER_UTILS_EXPORT substitute_envvar(std::string &line) noexcept;
139
140/*
141 * @brief Substitutes placeholder of particular environment variable in file
142 * path.
143 *
144 * @param s the file path in which variable name is substituted with value
145 * @param name The environment variable name
146 * @param value The environment variable value
147 *
148 * @return path to file
149 */
150std::string ROUTER_UTILS_EXPORT substitute_variable(const std::string &s,
151 const std::string &name,
152 const std::string &value);
153
154bool my_check_access(const std::string &path);
155
156/** @brief Copy contents of one file to another.
157 *
158 * Exception thrown if open, create read or write operation fails.
159 */
160void ROUTER_UTILS_EXPORT copy_file(const std::string &from,
161 const std::string &to);
162
163/**
164 * renames file.
165 *
166 * The function will overwrite the 'to' file if already exists.
167 *
168 * @param from old filename
169 * @param to new filename
170 *
171 * @returns stdx::expected<void, std::error_code>
172 */
174rename_file(const std::string &from, const std::string &to);
175
176/** @brief Returns whether the socket name passed as parameter is valid
177 */
178bool ROUTER_UTILS_EXPORT is_valid_socket_name(const std::string &socket,
179 std::string &err_msg);
180
181/** @brief Converts char array to signed integer, intuitively.
182 *
183 * Using strtol() can be daunting. This function wraps its with logic to ease
184 * its use. Features:
185 * - errno value is unaltered
186 * - on error, default value is returned
187 * - unlike strtol(), this function will fail (return default_result) if
188 * anything other than digits and sign are present in the char array. Inputs
189 * such as " 12" or "abc12.3" will fail, while strtol() would return 12.
190 *
191 * @param value char array to get converted
192 * @param default_result value to return in case of nullptr being passed
193 */
194int ROUTER_UTILS_EXPORT strtoi_checked(const char *value,
195 signed int default_result = 0) noexcept;
196
197/** @brief Converts char array to unsigned integer, intuitively.
198 * adding check for null parameter and some conversion restrictions.
199 *
200 * Using strtoul() can be daunting. This function wraps its with logic to ease
201 * its use. Features:
202 * - errno value is unaltered
203 * - on error, default value is returned
204 * - unlike strtoul(), this function will fail (return default_result) if
205 * anything other than digits and sign are present in the char array. Inputs
206 * such as " 12" or "abc12.3" will fail, while strtoul() would return 12.
207 *
208 * @param value char array to get converted
209 * @param default_result value to return in case of nullptr being passed
210 */
211unsigned ROUTER_UTILS_EXPORT
212strtoui_checked(const char *value, unsigned int default_result = 0) noexcept;
213
214uint64_t ROUTER_UTILS_EXPORT
215strtoull_checked(const char *value, uint64_t default_result = 0) noexcept;
216
217} // namespace mysqlrouter
218
219#endif // MYSQLROUTER_UTILS_INCLUDED
Definition: expected.h:284
Header for compiler-dependent features.
static int count
Definition: myisam_ftdump.cc:45
static char * path
Definition: mysqldump.cc:149
Definition: dim.h:358
bool my_check_access(const std::string &path)
Definition: utils.cc:78
mode_t perm_mode
Definition: utils.h:52
void ROUTER_UTILS_EXPORT copy_file(const std::string &from, const std::string &to)
Copy contents of one file to another.
Definition: utils.cc:86
unsigned ROUTER_UTILS_EXPORT strtoui_checked(const char *value, unsigned int default_result=0) noexcept
Converts char array to unsigned integer, intuitively.
Definition: utils.cc:407
int ROUTER_UTILS_EXPORT strtoi_checked(const char *value, signed int default_result=0) noexcept
Converts char array to signed integer, intuitively.
Definition: utils.cc:403
uint16_t ROUTER_UTILS_EXPORT get_tcp_port(const std::string &data)
Validates a string containing a TCP port.
Definition: utils.cc:187
uint64_t ROUTER_UTILS_EXPORT strtoull_checked(const char *value, uint64_t default_result=0) noexcept
Definition: utils.cc:412
bool ROUTER_UTILS_EXPORT is_valid_socket_name(const std::string &socket, std::string &err_msg)
Returns whether the socket name passed as parameter is valid.
Definition: utils.cc:303
bool ROUTER_UTILS_EXPORT substitute_envvar(std::string &line) noexcept
Substitutes placeholders of environment variables in a string.
Definition: utils.cc:131
std::string ROUTER_UTILS_EXPORT substitute_variable(const std::string &s, const std::string &name, const std::string &value)
Definition: utils.cc:161
const perm_mode ROUTER_UTILS_EXPORT kStrictDirectoryPerm
Constant for directory accessible only for the owner.
Definition: utils.cc:73
void ROUTER_UTILS_EXPORT set_prompt_password(const std::function< std::string(const std::string &)> &f)
Override default prompt password function.
Definition: utils.cc:267
stdx::expected< void, std::error_code > ROUTER_UTILS_EXPORT rename_file(const std::string &from, const std::string &to)
renames file.
Definition: utils.cc:108
std::string ROUTER_UTILS_EXPORT ms_to_seconds_string(const std::chrono::milliseconds &msec)
Definition: utils.cc:179
std::string hexdump(const unsigned char *buffer, size_t count)
Dumps buffer as hex values.
std::string ROUTER_UTILS_EXPORT prompt_password(const std::string &prompt)
Prompts for a password from the console.
Definition: utils.cc:272
std::string ROUTER_CLUSTER_EXPORT to_string(const MetadataSchemaVersion &version)
Definition: cluster_metadata.cc:420
stdx::expected< native_handle_type, error_type > socket(int family, int sock_type, int protocol)
Definition: socket.h:63
mutable_buffer buffer(void *p, size_t n) noexcept
Definition: buffer.h:418
std::basic_ostringstream< char, std::char_traits< char >, ut::allocator< char > > ostringstream
Specialization of basic_ostringstream which uses ut::allocator.
Definition: ut0new.h:2871
#define ROUTER_UTILS_EXPORT
Definition: router_utils_export.h:15
case opt name
Definition: sslopt-case.h:29