Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
++ // Qt-Security score:significant reason:default
++
++ #include "qsystemsemaphore.h"
++ #include "qsystemsemaphore_p.h"
++
++ #if QT_CONFIG(systemsemaphore)
++ #include <QtCore/q20memory.h>
++ #include <errno.h>
++
++ QT_BEGIN_NAMESPACE
++
++ using namespace QtIpcCommon;
++ using namespace Qt::StringLiterals;
++
++ inline void QSystemSemaphorePrivate::constructBackend()
++ {
++ visit([](auto p) { q20::construct_at(p); });
++ }
++
++ inline void QSystemSemaphorePrivate::destructBackend()
++ {
++ visit([](auto p) { std::destroy_at(p); });
++ }
++
++ /*!
++ \class QSystemSemaphore
++ \inmodule QtCore
++ \since 4.4
++
++ \brief The QSystemSemaphore class provides a general counting system semaphore.
++
++ A system semaphore is a generalization of \l QSemaphore. Typically, a
++ semaphore is used to protect a certain number of identical resources.
++
++ Like its lighter counterpart, a QSystemSemaphore can be
++ accessed from multiple \l {QThread} {threads}. Unlike QSemaphore, a
++ QSystemSemaphore can also be accessed from multiple \l {QProcess}
++ {processes}. This means QSystemSemaphore is a much heavier class, so
++ if your application doesn't need to access your semaphores across
++ multiple processes, you will probably want to use QSemaphore.
++
++ Semaphores support two fundamental operations, acquire() and release():
++
++ acquire() tries to acquire one resource. If there isn't a resource
++ available, the call blocks until a resource becomes available. Then
++ the resource is acquired and the call returns.
++
++ release() releases one resource so it can be acquired by another
++ process. The function can also be called with a parameter n > 1,
++ which releases n resources.
++
++ System semaphores are identified by a key, represented by \l QNativeIpcKey. A
++ key can be created in a cross-platform manner by using platformSafeKey(). A
++ system semaphore is created by the QSystemSemaphore constructor when passed
++ an access mode parameter of AccessMode::Create. Once it is created, other
++ processes may attach to the same semaphore using the same key and an access
++ mode parameter of AccessMode::Open.
++
++ Example: Create a system semaphore
++ \snippet code/src_corelib_kernel_qsystemsemaphore.cpp 0
++
++ For details on the key types, platform-specific limitations, and
++ interoperability with older or non-Qt applications, see the \l{Native IPC
++ Keys} documentation. That includes important information for sandboxed
++ applications on Apple platforms, including all apps obtained via the Apple
++ App Store.
++
++ \sa {Inter-Process Communication}, QSharedMemory, QSemaphore
++ */
++
++ /*!
++ Requests a system semaphore identified by the legacy key \a key.
++ */
++ QSystemSemaphore::QSystemSemaphore(const QString &key, int initialValue, AccessMode mode)
++ : QSystemSemaphore(legacyNativeKey(key), initialValue, mode)
++ {
++ }
++
++ /*!
++ Requests a system semaphore for the specified \a key. The parameters
++ \a initialValue and \a mode are used according to the following
++ rules, which are system dependent.
++
++ In Unix, if the \a mode is \l {QSystemSemaphore::} {Open} and the
++ system already has a semaphore identified by \a key, that semaphore
++ is used, and the semaphore's resource count is not changed, i.e., \a
++ initialValue is ignored. But if the system does not already have a
++ semaphore identified by \a key, it creates a new semaphore for that
++ key and sets its resource count to \a initialValue.
++
++ In Unix, if the \a mode is \l {QSystemSemaphore::} {Create} and the
++ system already has a semaphore identified by \a key, that semaphore
++ is used, and its resource count is set to \a initialValue. If the
++ system does not already have a semaphore identified by \a key, it
++ creates a new semaphore for that key and sets its resource count to
++ \a initialValue.
++
++ In Windows, \a mode is ignored, and the system always tries to
++ create a semaphore for the specified \a key. If the system does not
++ already have a semaphore identified as \a key, it creates the
++ semaphore and sets its resource count to \a initialValue. But if the
++ system already has a semaphore identified as \a key it uses that
++ semaphore and ignores \a initialValue.
++
++ The \l {QSystemSemaphore::AccessMode} {mode} parameter is only used
++ in Unix systems to handle the case where a semaphore survives a
++ process crash. In that case, the next process to allocate a
++ semaphore with the same \a key will get the semaphore that survived
++ the crash, and unless \a mode is \l {QSystemSemaphore::} {Create},
++ the resource count will not be reset to \a initialValue but will
++ retain the initial value it had been given by the crashed process.
++
++ \sa acquire(), key()
++ */
++ QSystemSemaphore::QSystemSemaphore(const QNativeIpcKey &key, int initialValue, AccessMode mode)
++ : d(new QSystemSemaphorePrivate(key.type()))
++ {
++ setNativeKey(key, initialValue, mode);
++ }
++
++ /*!
++ The destructor destroys the QSystemSemaphore object, but the
++ underlying system semaphore is not removed from the system unless
++ this instance of QSystemSemaphore is the last one existing for that
++ system semaphore.
++
++ Two important side effects of the destructor depend on the system.
++ In Windows, if acquire() has been called for this semaphore but not
++ release(), release() will not be called by the destructor, nor will
++ the resource be released when the process exits normally. This would
++ be a program bug which could be the cause of a deadlock in another
++ process trying to acquire the same resource. In Unix, acquired
++ resources that are not released before the destructor is called are
++ automatically released when the process exits.
++ */
++ QSystemSemaphore::~QSystemSemaphore()
++ {
++ d->cleanHandle();
++ }
++
++ /*!
++ \enum QSystemSemaphore::AccessMode
++
++ This enum is used by the constructor and setKey(). Its purpose is to
++ enable handling the problem in Unix implementations of semaphores
++ that survive a crash. In Unix, when a semaphore survives a crash, we
++ need a way to force it to reset its resource count, when the system
++ reuses the semaphore. In Windows, where semaphores can't survive a
++ crash, this enum has no effect.
++
++ \value Open If the semaphore already exists, its initial resource
++ count is not reset. If the semaphore does not already exist, it is
++ created and its initial resource count set.
++
++ \value Create QSystemSemaphore takes ownership of the semaphore and
++ sets its resource count to the requested value, regardless of
++ whether the semaphore already exists by having survived a crash.
++ This value should be passed to the constructor, when the first
++ semaphore for a particular key is constructed and you know that if
++ the semaphore already exists it could only be because of a crash. In
++ Windows, where a semaphore can't survive a crash, Create and Open
++ have the same behavior.
++ */
++
++ /*!
++ This function works the same as the constructor. It reconstructs
++ this QSystemSemaphore object. If the new \a key is different from
++ the old key, calling this function is like calling the destructor of
++ the semaphore with the old key, then calling the constructor to
++ create a new semaphore with the new \a key. The \a initialValue and
++ \a mode parameters are as defined for the constructor.
++
++ This function is useful if the native key was shared from another process.
++ See \l{Native IPC Keys} for more information.
++
++ \sa QSystemSemaphore(), nativeIpcKey()
++ */
++ void QSystemSemaphore::setNativeKey(const QNativeIpcKey &key, int initialValue, AccessMode mode)
++ {
++ if (key == d->nativeKey && mode == Open)
++ return;
++ if (!isKeyTypeSupported(key.type())) {
++ d->setError(KeyError, tr("%1: unsupported key type")
++ .arg("QSystemSemaphore::setNativeKey"_L1));
++ return;
++ }
++
++ d->clearError();
++ d->cleanHandle();
++ if (key.type() == d->nativeKey.type()) {
++ // we can reuse the backend
++ d->nativeKey = key;
++ } else {
++ // we must recreate the backend
++ d->destructBackend();
++ d->nativeKey = key;
++ d->constructBackend();
++ }
++ d->initialValue = initialValue;
++ d->handle(mode);
++ }
++
++ /*!
++ Returns the key assigned to this system semaphore. The key is the
++ name by which the semaphore can be accessed from other processes.
++
++ You can use the native key to access system semaphores that have not been
++ created by Qt, or to grant access to non-Qt applications. See \l{Native IPC
++ Keys} for more information.
++
++ \sa setNativeKey()
++ */
++ QNativeIpcKey QSystemSemaphore::nativeIpcKey() const
++ {
++ return d->nativeKey;
++ }
++
++ /*!
++ This function works the same as the constructor. It reconstructs
++ this QSystemSemaphore object. If the new \a key is different from
++ the old key, calling this function is like calling the destructor of
++ the semaphore with the old key, then calling the constructor to
++ create a new semaphore with the new \a key. The \a initialValue and
++ \a mode parameters are as defined for the constructor.
++
++ \sa QSystemSemaphore(), key()
++ */
++ void QSystemSemaphore::setKey(const QString &key, int initialValue, AccessMode mode)
++ {
++ setNativeKey(legacyNativeKey(key), initialValue, mode);
++ }
++
++ /*!
++ Returns the legacy key assigned to this system semaphore. The key is the
++ name by which the semaphore can be accessed from other processes.
++
++ \sa setKey()
++ */
++ QString QSystemSemaphore::key() const
++ {
++ return QNativeIpcKeyPrivate::legacyKey(d->nativeKey);
++ }
++
++ /*!
++ Acquires one of the resources guarded by this semaphore, if there is
++ one available, and returns \c true. If all the resources guarded by this
++ semaphore have already been acquired, the call blocks until one of
++ them is released by another process or thread having a semaphore
++ with the same key.
++
++ If false is returned, a system error has occurred. Call error()
++ to get a value of QSystemSemaphore::SystemSemaphoreError that
++ indicates which error occurred.
++
++ \sa release()
++ */
++ bool QSystemSemaphore::acquire()
++ {
++ return d->modifySemaphore(-1);
++ }
++
++ /*!
++ Releases \a n resources guarded by the semaphore. Returns \c true
++ unless there is a system error.
++
++ Example: Create a system semaphore having five resources; acquire
++ them all and then release them all.
++
++ \snippet code/src_corelib_kernel_qsystemsemaphore.cpp 1
++
++ This function can also "create" resources. For example, immediately
++ following the sequence of statements above, suppose we add the
++ statement:
++
++ \snippet code/src_corelib_kernel_qsystemsemaphore.cpp 2
++
++ Ten new resources are now guarded by the semaphore, in addition to
++ the five that already existed. You would not normally use this
++ function to create more resources.
++
++ \sa acquire()
++ */
++ bool QSystemSemaphore::release(int n)
++ {
++ if (n == 0)
++ return true;
++ if (n < 0) {
++ qWarning("QSystemSemaphore::release: n is negative.");
++ return false;
++ }
++ return d->modifySemaphore(n);
++ }
++
++ /*!
++ Returns a value indicating whether an error occurred, and, if so,
++ which error it was.
++
++ \sa errorString()
++ */
++ QSystemSemaphore::SystemSemaphoreError QSystemSemaphore::error() const
++ {
++ return d->error;
++ }
++
++ /*!
++ \enum QSystemSemaphore::SystemSemaphoreError
++
++ \value NoError No error occurred.
++
++ \value PermissionDenied The operation failed because the caller
++ didn't have the required permissions.
++
++ \value KeyError The operation failed because of an invalid key.
++
++ \value AlreadyExists The operation failed because a system
++ semaphore with the specified key already existed.
++
++ \value NotFound The operation failed because a system semaphore
++ with the specified key could not be found.
++
++ \value OutOfResources The operation failed because there was
++ not enough memory available to fill the request.
++
++ \value UnknownError Something else happened and it was bad.
++ */
++
++ /*!
++ Returns a text description of the last error that occurred. If
++ error() returns an \l {QSystemSemaphore::SystemSemaphoreError} {error
++ value}, call this function to get a text string that describes the
++ error.
++
++ \sa error()
++ */
++ QString QSystemSemaphore::errorString() const
++ {
++ return d->errorString;
++ }
++
++ void QSystemSemaphorePrivate::setUnixErrorString(QLatin1StringView function)
++ {
++ // EINVAL is handled in functions so they can give better error strings
++ switch (errno) {
++ case EPERM:
++ case EACCES:
++ errorString = QSystemSemaphore::tr("%1: permission denied").arg(function);
++ error = QSystemSemaphore::PermissionDenied;
++ break;
++ case EEXIST:
++ errorString = QSystemSemaphore::tr("%1: already exists").arg(function);
++ error = QSystemSemaphore::AlreadyExists;
++ break;
++ case ENOENT:
++ errorString = QSystemSemaphore::tr("%1: does not exist").arg(function);
++ error = QSystemSemaphore::NotFound;
++ break;
++ case ERANGE:
++ case ENOSPC:
++ case EMFILE:
++ errorString = QSystemSemaphore::tr("%1: out of resources").arg(function);
++ error = QSystemSemaphore::OutOfResources;
++ break;
++ case ENAMETOOLONG:
++ errorString = QSystemSemaphore::tr("%1: key too long").arg(function);
++ error = QSystemSemaphore::KeyError;
++ break;
++ default:
++ errorString = QSystemSemaphore::tr("%1: unknown error: %2")
++ .arg(function, qt_error_string(errno));
++ error = QSystemSemaphore::UnknownError;
++ #if defined QSYSTEMSEMAPHORE_DEBUG
++ qDebug() << errorString << "key" << key << "errno" << errno << EINVAL;
++ #endif
++ }
++ }
++
++ bool QSystemSemaphore::isKeyTypeSupported(QNativeIpcKey::Type type)
++ {
++ if (!isIpcSupported(IpcType::SystemSemaphore, type))
++ return false;
++ using Variant = decltype(QSystemSemaphorePrivate::backend);
++ return Variant::staticVisit(type, [](auto ptr) {
++ using Impl = std::decay_t<decltype(*ptr)>;
++ return Impl::runtimeSupportCheck();
++ });
++ }
++
++ QNativeIpcKey QSystemSemaphore::platformSafeKey(const QString &key, QNativeIpcKey::Type type)
++ {
++ return QtIpcCommon::platformSafeKey(key, IpcType::SystemSemaphore, type);
++ }
++
++ QNativeIpcKey QSystemSemaphore::legacyNativeKey(const QString &key, QNativeIpcKey::Type type)
++ {
++ return QtIpcCommon::legacyPlatformSafeKey(key, IpcType::SystemSemaphore, type);
++ }
++
++ QT_END_NAMESPACE
++
++ #include "moc_qsystemsemaphore.cpp"
++
++ #endif // QT_CONFIG(systemsemaphore)