Submit
Path:
~
/
/
proc
/
thread-self
/
root
/
opt
/
cpanel
/
ea-ruby27
/
src
/
passenger-release-6.1.2
/
src
/
cxx_supportlib
/
IOTools
/
File Content:
IOUtils.h
/* * Phusion Passenger - https://www.phusionpassenger.com/ * Copyright (c) 2010-2025 Asynchronous B.V. * * "Passenger", "Phusion Passenger" and "Union Station" are registered * trademarks of Asynchronous B.V. * * Permission is hereby granted, free of charge, to any person obtaining a copy * of this software and associated documentation files (the "Software"), to deal * in the Software without restriction, including without limitation the rights * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell * copies of the Software, and to permit persons to whom the Software is * furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included in * all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN * THE SOFTWARE. */ #ifndef _PASSENGER_IOTOOLS_IO_UTILS_H_ #define _PASSENGER_IOTOOLS_IO_UTILS_H_ #include <sys/types.h> #include <sys/socket.h> #include <sys/uio.h> #include <cstdio> #include <cstddef> #include <unistd.h> #include <netdb.h> #include <string> #include <utility> #include <oxt/macros.hpp> #include <StaticString.h> #include <FileDescriptor.h> namespace Passenger { using namespace std; /****** Server address types support ******/ enum ServerAddressType { SAT_UNIX, SAT_TCP, SAT_UNKNOWN }; /** * Accepts a server address in one of the following formats, and returns which one it is: * * Unix domain sockets * Format: "unix:/path/to/a/socket" * Returns: SAT_UNIX * * TCP sockets * Format: "tcp://host:port" * Returns: SAT_TCP * * Other * Returns: SAT_UNKNOWN */ ServerAddressType getSocketAddressType(const StaticString &address); /** * Parses a Unix domain socket address, as accepted by getSocketAddressType(), * and returns the socket filename. * * @throw ArgumentException <tt>address</tt> is not a valid Unix domain socket address. */ string parseUnixSocketAddress(const StaticString &address); /** * Parses a TCP socket address, as accepted by getSocketAddressType(), * and returns the host and port. * * @throw ArgumentException <tt>address</tt> is not a valid TCP socket address. */ void parseTcpSocketAddress(const StaticString & restrict_ref address, string & restrict_ref host, unsigned short & restrict_ref port); /** * Returns whether the given socket address (as accepted by getSocketAddressType()) * is an address that can only refer to a server on the local system. * * @throw ArgumentException <tt>address</tt> is not a valid TCP socket address. */ bool isLocalSocketAddress(const StaticString &address); /****** Server socket creation ******/ /** * Create a new Unix or TCP server socket, depending on the address type. * * @param address An address as defined by getSocketAddressType(). * @param backlogSize The size of the socket's backlog. Specify 0 to use * the paltform's maximum allowed backlog size. * @param autoDelete If <tt>address</tt> is a Unix socket that already exists, * whether that should be deleted. Otherwise this argument * is ignored. * @param file The name of the source file that called this function, * for file descriptor logging purposes. * @param line The line in the source file that called this function. * @return The file descriptor of the newly created server socket. * @throws ArgumentException The given address cannot be parsed. * @throws RuntimeException Something went wrong. * @throws SystemException Something went wrong while creating the Unix server socket. * @throws boost::thread_interrupted A system call has been interrupted. * @ingroup Support */ int createServer(const StaticString &address, unsigned int backlogSize = 0, bool autoDelete = true, const char *file = __FILE__, unsigned int line = __LINE__); /** * Create a new Unix server socket which is bounded to <tt>filename</tt>. * * @param filename The filename to bind the socket to. * @param backlogSize The size of the socket's backlog. Specify 0 to use the * platform's maximum allowed backlog size. * @param autoDelete Whether <tt>filename</tt> should be deleted, if it already exists. * @param file The name of the source file that called this function, * for file descriptor logging purposes. * @param line The line in the source file that called this function. * @return The file descriptor of the newly created Unix server socket. * @throws RuntimeException Something went wrong. * @throws SystemException Something went wrong while creating the Unix server socket. * @throws boost::thread_interrupted A system call has been interrupted. * @ingroup Support */ int createUnixServer(const StaticString &filename, unsigned int backlogSize = 0, bool autoDelete = true, const char *file = __FILE__, unsigned int line = __LINE__); /** * Create a new TCP server socket which is bounded to the given address and port. * SO_REUSEADDR will be set on the socket. * * @param address The IP address to bind the socket to. * @param port The port to bind the socket to, or 0 to have the OS automatically * select a free port. * @param backlogSize The size of the socket's backlog. Specify 0 to use the * platform's maximum allowed backlog size. * @param file The name of the source file that called this function, * for file descriptor logging purposes. * @param line The line in the source file that called this function. * @return The file descriptor of the newly created server socket. * @throws SystemException Something went wrong while creating the server socket. * @throws ArgumentException The given address cannot be parsed. * @throws boost::thread_interrupted A system call has been interrupted. * @ingroup Support */ int createTcpServer(const char *address = "0.0.0.0", unsigned short port = 0, unsigned int backlogSize = 0, const char *file = __FILE__, unsigned int line = __LINE__); /****** Socket connection establishment (blocking) ******/ /** * Connect to a server at the given address in a blocking manner. * * @param address An address as accepted by getSocketAddressType(). * @param file The name of the source file that called this function, * for file descriptor logging purposes. * @param line The line in the source file that called this function. * @return The file descriptor of the connected client socket. * @throws ArgumentException Unknown address type. * @throws RuntimeException Something went wrong. * @throws SystemException Something went wrong while connecting to the server. * @throws IOException Something went wrong while connecting to the server. * @throws boost::thread_interrupted A system call has been interrupted. * @ingroup Support */ int connectToServer(const StaticString &address, const char *file, unsigned int line); /** * Connect to a Unix server socket at <tt>filename</tt> in a blocking manner. * * @param filename The filename of the socket to connect to. * @param file The name of the source file that called this function, * for file descriptor logging purposes. * @param line The line in the source file that called this function. * @return The file descriptor of the connected client socket. * @throws RuntimeException Something went wrong. * @throws SystemException Something went wrong while connecting to the Unix server. * @throws boost::thread_interrupted A system call has been interrupted. * @ingroup Support */ int connectToUnixServer(const StaticString &filename, const char *file, unsigned int line); /** * Connect to a TCP server socket at the given host name and port in a blocking manner. * * @param hostname The host name of the TCP server. * @param port The port number of the TCP server. * @param file The name of the source file that called this function, * for file descriptor logging purposes. * @param line The line in the source file that called this function. * @return The file descriptor of the connected client socket. * @throws IOException Something went wrong while connecting to the Unix server. * @throws SystemException Something went wrong while connecting to the server. * @throws boost::thread_interrupted A system call has been interrupted. * @ingroup Support */ int connectToTcpServer(const StaticString &hostname, unsigned int port, const char *file, unsigned int line); /****** Socket connection establishment (non-blocking) ******/ /** * Establish a socket connection in non-blocking mode. * * @param address An address as accepted by getSocketAddressType(). * @param file The name of the source file that called this function, * for file descriptor logging purposes. * @param line The line in the source file that called this function. * @return The file descriptor of the connected client socket, plus whether * it was immediately connected (true) or pending (false). If pending, * the caller should poll() on the socket until it's writable. * @throws ArgumentException Something went wrong. * @throws IOException Something went wrong. * @throws SystemException Something went wrong. * @throws boost::thread_interrupted A system call has been interrupted. */ std::pair<int, bool> createNonBlockingSocketConnection(const StaticString &address, const char *file, unsigned int line); /** * Establish a Unix domain socket connection in non-blocking mode. * * @param filename The filename of the socket to connect to. * @param file The name of the source file that called this function, * for file descriptor logging purposes. * @param line The line in the source file that called this function. * @return The file descriptor of the connected client socket, plus whether * it was immediately connected (true) or pending (false). If pending, * the caller should poll() on the socket until it's writable. * @throws ArgumentException Something went wrong. * @throws SystemException Something went wrong while connecting to the Unix server. * @throws boost::thread_interrupted A system call has been interrupted. */ std::pair<int, bool> createNonBlockingUnixSocketConnection(const StaticString &filename, const char *file, unsigned int line); /** * Establish a TCP socket connection in non-blocking mode. * * @param hostname The host name of the TCP server. * @param port The port number of the TCP server. * @param file The name of the source file that called this function, * for file descriptor logging purposes. * @param line The line in the source file that called this function. * @return The file descriptor of the connected client socket, plus whether * it was immediately connected (true) or pending (false). If pending, * the caller should poll() on the socket until it's writable. * @throws IOException Something went wrong. * @throws SystemException Something went wrong. * @throws boost::thread_interrupted A system call has been interrupted. */ std::pair<int, bool> createNonBlockingTcpSocketConnection(const StaticString &hostname, unsigned int port, const char *file, unsigned int line); /****** Scope guards ******/ /** RAII construct for ensuring that a file descriptor gets closed at scope exit. */ class FdGuard { private: int mFd = -1; public: FdGuard() { } FdGuard(const FdGuard &other) = delete; FdGuard(FdGuard &&other); FdGuard(int fd, const char *sourceFile, unsigned int sourceLine); /** @throws SystemException File descriptor close error. If exception is already being thrown, then only warns. */ ~FdGuard() noexcept(false); FdGuard &operator=(const FdGuard &other) = delete; FdGuard &operator=(FdGuard &&other); /** Don't close file descriptor at object destruction. */ void clear() noexcept; /** * Close file descriptor now. Idempotent. * * @throws SystemException */ void runNow() noexcept(false); }; /****** Other ******/ typedef ssize_t (*WritevFunction)(int fildes, const struct iovec *iov, int iovcnt); bool purgeStdio(FILE *f); /** * Sets a socket in blocking mode. * * @throws SystemException Something went wrong. * @ingroup Support */ void setBlocking(int fd); /** * Sets a socket in non-blocking mode. * * @throws SystemException Something went wrong. * @ingroup Support */ void setNonBlocking(int fd); /** * Try to call the Linux accept4() system call. If the system call is * not available, then -1 is returned and errno is set to ENOSYS. */ int callAccept4(int sock, struct sockaddr * restrict addr, socklen_t * restrict addr_len, int options); /** * Checks whether the given TCP server is connectable. Because this check * can take (in theory) an arbitrary amount of time, you must also supply * a timeout. When the operation is done, the amount of time taken will be * deducted from the `*timeout` value. A timeout of 100000 microseconds is * recommended for most use cases. * * @throws ArgumentException Something went wrong. * @throws IOException Something went wrong. * @throws SystemException Something went wrong. * @throws boost::thread_interrupted A system call has been interrupted. */ bool pingTcpServer(const StaticString &host, unsigned int port, unsigned long long *timeout); /** * Creates a Unix domain socket pair. * * @param file The name of the source file that called this function, * for file descriptor logging purposes. * @param line The line in the source file that called this function. * @throws SystemException * @throws boost::thread_interrupted */ SocketPair createUnixSocketPair(const char *file, unsigned int line); /** * Creates a pipe. * * @param file The name of the source file that called this function, * for file descriptor logging purposes. * @param line The line in the source file that called this function. * @throws SystemException * @throws boost::thread_interrupted */ Pipe createPipe(const char *file, unsigned int line); /** * Waits at most <tt>*timeout</tt> microseconds for the file descriptor to become readable. * Returns true if it become readable within the timeout, false if the timeout expired. * * <tt>*timeout</tt> may be 0, in which case this method will check whether the file * descriptor is readable, and immediately returns without waiting. * * If no exception is thrown, this method deducts the number of microseconds that has * passed from <tt>*timeout</tt>. * * @throws SystemException * @throws boost::thread_interrupted */ bool waitUntilReadable(int fd, unsigned long long *timeout); /** * Waits at most <tt>*timeout</tt> microseconds for the file descriptor to become writable. * Returns true if it become writable within the timeout, false if the timeout expired. * * <tt>*timeout</tt> may be 0, in which case this method will check whether the file * descriptor is writable, and immediately returns without waiting. * * If no exception is thrown, this method deducts the number of microseconds that has * passed from <tt>*timeout</tt>. * * @throws SystemException * @throws boost::thread_interrupted */ bool waitUntilWritable(int fd, unsigned long long *timeout); /** * Attempts to read exactly `size` bytes of data, putting the result in `buf`. * This is in contrast to read(), which may read less than `size` bytes even * when EOF is not reached. * * On non-blocking sockets, this function blocks by poll()ing the socket. * * @param buf The buffer to place the read data in. This buffer must be at least * <tt>size</tt> bytes long. * @param size The number of bytes to read. * @param timeout A pointer to an integer, which specifies the maximum number of * microseconds that may be spent on reading the <tt>size</tt> bytes * of data. If the timeout expired then TimeoutException will be * thrown. * If this function returns without throwing an exception, then the * total number of microseconds spent on reading will be deducted * from <tt>timeout</tt>. * Pass NULL if you do not want to enforce a timeout. * @return The number of bytes read. This is exactly equal to <em>size</em>, * except when EOF is encountered prematurely. * @pre buf != NULL * @throws SystemException * @throws TimeoutException Unable to read <tt>size</tt> bytes of data within * <tt>timeout</tt> microseconds. * @throws boost::thread_interrupted */ unsigned int readExact(int fd, void * restrict buf, unsigned int size, unsigned long long * restrict timeout = NULL); /** * Writes a block of data to the given file descriptor and blocks until everything * is written, even for non-blocking sockets. If not everything can be written (e.g. * because the peer closed the connection before accepting everything) then an * exception will be thrown. * * @note Security guarantee: this method will not copy the data in memory, * so it's safe to use this method to write passwords to the underlying * file descriptor. * * @param data The data to send. * @param size The number of bytes in <tt>data</tt>. * @param timeout A pointer to an integer, which specifies the maximum number of * microseconds that may be spent on writing the <tt>size</tt> bytes * of data. If the timeout expired then TimeoutException will be * thrown. * If this function returns without throwing an exception, then the * total number of microseconds spent on writing will be deducted * from <tt>timeout</tt>. * Pass NULL if you do not want to enforce a timeout. * @pre data != NULL * @throws SystemException * @throws TimeoutException Unable to write <tt>size</tt> bytes of data within * <tt>timeout</tt> microseconds. * @throws boost::thread_interrupted */ void writeExact(int fd, const void * restrict data, unsigned int size, unsigned long long * restrict timeout = NULL); void writeExact(int fd, const StaticString & restrict_ref data, unsigned long long * restrict timeout = NULL); /** * Writes a bunch of data to the given file descriptor using a gathering I/O interface. * Instead of accepting a single buffer, this function accepts multiple buffers plus * a special 'rest' buffer. The rest buffer is written out first, and the data buffers * are then written out in the order as they appear. This all is done with a single * writev() system call without concatenating all data into a single buffer. * * This function is designed for use with non-blocking sockets. It returns the number * of bytes that have been written, and ensures that restBuffer will contain all data * that has not been written, i.e. should be written out as soon as the file descriptor * is writeable again. If everything has been successfully written out then restBuffer * will be empty. * A return value of 0 indicates that nothing could be written without blocking. * * Returns -1 if an error occurred other than one which indicates blocking. In this * case, <tt>errno</tt> is set appropriately. * * This function also takes care of all the stupid writev() limitations such as * IOV_MAX. It ensures that no more than IOV_MAX items will be passed to writev(). * * @param fd The file descriptor to write to. * @param data The data to write. * @param dataCount Number of elements in <tt>data</tt>. * @param restBuffer The rest buffer, as documented above. * @return The number of bytes that have been written out, or -1 on any error that * isn't related to non-blocking writes. * @throws boost::thread_interrupted */ ssize_t gatheredWrite(int fd, const StaticString * restrict data, unsigned int dataCount, string & restrict_ref restBuffer); /** * Writes a bunch of data to the given file descriptor using a gathering I/O interface. * Instead of accepting a single buffer, this function accepts multiple buffers * which are all written out in the order as they appear. This is done with a single * system call without concatenating all data into a single buffer. * * This method is a convenience wrapper around writev() but it blocks until all data * has been written and takes care of handling system limits (IOV_MAX) for you. * * This version is designed for blocking sockets so do not use it on non-blocking ones. * * @param fd The file descriptor to write to. * @param data An array of buffers to be written. * @param count Number of items in <em>data</em>. * @param timeout A pointer to an integer, which specifies the maximum number of * microseconds that may be spent on writing all the data. * If the timeout expired then TimeoutException will be thrown. * If this function returns without throwing an exception, then the * total number of microseconds spent on writing will be deducted * from <tt>timeout</tt>. * Pass NULL if you do not want to enforce a timeout. * @throws SystemException Something went wrong. * @throws TimeoutException Unable to write all given data within * <tt>timeout</tt> microseconds. * @throws boost::thread_interrupted */ void gatheredWrite(int fd, const StaticString * restrict data, unsigned int dataCount, unsigned long long * restrict timeout = NULL); /** * Sets a writev-emulating function that gatheredWrite() should call instead of the real writev(). * Useful for unit tests. Pass NULL to restore back to the real writev(). */ void setWritevFunction(WritevFunction func); /** * Receive a file descriptor over the given Unix domain socket. * This is a low-level function that directly wraps the Unix file * descriptor passing system calls. You should not use this directly; * instead you should use readFileDescriptorWithNegotiation() from MessageIO.h * which is safer. See MessageIO.h for more information about the * negotiation protocol for file descriptor passing. * * @param timeout A pointer to an integer, which specifies the maximum number of * microseconds that may be spent on receiving the file descriptor. * If the timeout expired then TimeoutException will be thrown. * If this function returns without throwing an exception, then the * total number of microseconds spent on receiving will be deducted * from <tt>timeout</tt>. * Pass NULL if you do not want to enforce a timeout. * @return The received file descriptor. * @throws SystemException Something went wrong. * @throws IOException Whatever was received doesn't seem to be a * file descriptor. * @throws TimeoutException Unable to receive a file descriptor within * <tt>timeout</tt> microseconds. * @throws boost::thread_interrupted */ int readFileDescriptor(int fd, unsigned long long *timeout = NULL); /** * Pass the file descriptor 'fdToSend' over the Unix socket 'fd'. * This is a low-level function that directly wraps the Unix file * descriptor passing system calls. You should not use this directly; * instead you should use writeFileDescriptorWithNegotiation() from MessageIO.h * which is safer. See MessageIO.h for more information about the * negotiation protocol for file descriptor passing. * * @param timeout A pointer to an integer, which specifies the maximum number of * microseconds that may be spent on trying to pass the file descriptor. * If the timeout expired then TimeoutException will be thrown. * If this function returns without throwing an exception, then the * total number of microseconds spent on writing will be deducted * from <tt>timeout</tt>. * Pass NULL if you do not want to enforce a timeout. * @throws SystemException Something went wrong. * @throws TimeoutException Unable to pass the file descriptor within * <tt>timeout</tt> microseconds. * @throws boost::thread_interrupted */ void writeFileDescriptor(int fd, int fdToSend, unsigned long long *timeout = NULL); /** * Return the effective UID and GID of the peer connected to a Unix domain socket. * * @throws SystemException Something went wrong. If reading credentials over a Unix * domain socket is not supported for the current platform, * then the error code is ENOSYS. If the socket does not * support credentials passing, then the error code is * EPROTONOSUPPORT. */ void readPeerCredentials(int sock, uid_t *uid, gid_t *gid); /** * Closes the given file descriptor and throws an exception if anything goes wrong. * This function also works around certain close() bugs and quirks on certain * operating systems, such as the FreeBSD ENOTCONN-on-close bug and the fact that * when close() returns EINTR the state of the file descriptor is unspecified. * See IOUtils.cpp and ext/oxt/system_calls.cpp for details. * * @throws SystemException * @throws boost::thread_interrupted */ #ifndef _PASSENGER_SAFELY_CLOSE_DEFINED_ #define _PASSENGER_SAFELY_CLOSE_DEFINED_ void safelyClose(int fd, bool ignoreErrors = false); #endif /** * Read all data from the given file descriptor until EOF, or until `maxSize` * is reached. * * Returns a pair `(contents, eof)`. * * - `contents` is the read file contents, which is at most `maxSize` bytes. * - `eof` indicates whether the entire file has been read. If false, then it * means the amount of data is larger than `maxSize`. * * @throws SystemException */ pair<string, bool> readAll(int fd, size_t maxSize); } // namespace Passenger #endif /* _PASSENGER_IOTOOLS_IO_UTILS_H_ */
Edit
Rename
Chmod
Delete
FILE
FOLDER
Name
Size
Permission
Action
BufferedIO.h
8255 bytes
0644
IOUtils.cpp
37080 bytes
0644
IOUtils.h
26399 bytes
0644
MessageIO.h
25170 bytes
0644
MessageSerialization.h
15166 bytes
0644
N4ST4R_ID | Naxtarrr