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