|
Packit Service |
310c69 |
/*
|
|
Packit Service |
310c69 |
* Copyright (c) 2020 Red Hat, Inc.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* This program is free software; you can redistribute it and/or
|
|
Packit Service |
310c69 |
* modify it under the terms of the GNU General Public License
|
|
Packit Service |
310c69 |
* as published by the Free Software Foundation; either version 2
|
|
Packit Service |
310c69 |
* of the License, or (at your option) any later version.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* This program is distributed in the hope that it will be useful,
|
|
Packit Service |
310c69 |
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
Packit Service |
310c69 |
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
Packit Service |
310c69 |
* GNU General Public License for more details.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* You should have received a copy of the GNU General Public License
|
|
Packit Service |
310c69 |
* along with this program; if not, write to the Free Software
|
|
Packit Service |
310c69 |
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
|
|
Packit Service |
310c69 |
* 02110-1301, USA.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* $Id: //eng/uds-releases/jasper/src/uds/uds.h#2 $
|
|
Packit Service |
310c69 |
*/
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* @mainpage UDS API Reference
|
|
Packit Service |
310c69 |
* <center>Copyright (c) 2020 Red Hat, Inc.</center>
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* @file
|
|
Packit Service |
310c69 |
* @brief General UDS definitions
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
#ifndef UDS_H
|
|
Packit Service |
310c69 |
#define UDS_H
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
#include "uds-platform.h"
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
#ifdef UDS_DISABLE_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
#define UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
#else
|
|
Packit Service |
310c69 |
#define UDS_ATTR_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
|
|
Packit Service |
310c69 |
#endif
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Valid request types as described in callbacks.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
typedef enum {
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Callback type for operations that post mappings to the UDS
|
|
Packit Service |
310c69 |
* index. When the chunk-hash being added already exists, the
|
|
Packit Service |
310c69 |
* existing metadata is not overwritten. Regardless, the
|
|
Packit Service |
310c69 |
* recency of the chunk is updated.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_POST,
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Callback type for operations that update mappings in the UDS
|
|
Packit Service |
310c69 |
* index. If the indicated entry does not have any mapping in the
|
|
Packit Service |
310c69 |
* index, one is created. In either case, the recency of
|
|
Packit Service |
310c69 |
* the chunk is updated.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_UPDATE,
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Callback type for operations that delete mappings from the
|
|
Packit Service |
310c69 |
* UDS index. */
|
|
Packit Service |
310c69 |
UDS_DELETE,
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Callback type for operations that query mappings in the UDS
|
|
Packit Service |
310c69 |
* index. When a mapping is found, the recency of the mapping
|
|
Packit Service |
310c69 |
* is updated unless it's the no-update call.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_QUERY
|
|
Packit Service |
310c69 |
} UdsCallbackType;
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Valid types for opening an index.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
typedef enum {
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Load an existing index. If the index was not saved cleanly, try to
|
|
Packit Service |
310c69 |
* recover and rebuild the index.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_LOAD = 0,
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Create a new index.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_CREATE = 1,
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Load an existing index, but only if it was cleanly saved.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_NO_REBUILD = 2,
|
|
Packit Service |
310c69 |
} UdsOpenIndexType;
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/** General UDS constants. */
|
|
Packit Service |
310c69 |
enum {
|
|
Packit Service |
310c69 |
/** The chunk name size in bytes (128 bits = 16 bytes). */
|
|
Packit Service |
310c69 |
UDS_CHUNK_NAME_SIZE = 16,
|
|
Packit Service |
310c69 |
/** The maximum metadata size in bytes. */
|
|
Packit Service |
310c69 |
UDS_MAX_METADATA_SIZE = 16,
|
|
Packit Service |
310c69 |
};
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Type representing memory configuration which is either a positive
|
|
Packit Service |
310c69 |
* integer number of gigabytes or one of the three special constants
|
|
Packit Service |
310c69 |
* for configurations which are smaller than 1 gigabyte.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
typedef unsigned int UdsMemoryConfigSize;
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
extern const UdsMemoryConfigSize UDS_MEMORY_CONFIG_256MB;
|
|
Packit Service |
310c69 |
extern const UdsMemoryConfigSize UDS_MEMORY_CONFIG_512MB;
|
|
Packit Service |
310c69 |
extern const UdsMemoryConfigSize UDS_MEMORY_CONFIG_768MB;
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The maximum configurable amount of memory.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
extern const UdsMemoryConfigSize UDS_MEMORY_CONFIG_MAX;
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/** The name (hash) of a chunk. */
|
|
Packit Service |
310c69 |
typedef struct udsChunkName {
|
|
Packit Service |
310c69 |
/** The name (hash) of a chunk. */
|
|
Packit Service |
310c69 |
unsigned char name[UDS_CHUNK_NAME_SIZE];
|
|
Packit Service |
310c69 |
} UdsChunkName;
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* An active index session.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
struct uds_index_session;
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The data used to configure a new index.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
typedef struct udsConfiguration *UdsConfiguration;
|
|
Packit Service |
310c69 |
typedef uint64_t UdsNonce;
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The data used to configure a new index session.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
struct uds_parameters {
|
|
Packit Service |
310c69 |
// Tne number of threads used to process index requests.
|
|
Packit Service |
310c69 |
int zone_count;
|
|
Packit Service |
310c69 |
// The number of threads used to read volume pages.
|
|
Packit Service |
310c69 |
int read_threads;
|
|
Packit Service |
310c69 |
// The number of chapters to write between checkpoints.
|
|
Packit Service |
310c69 |
int checkpoint_frequency;
|
|
Packit Service |
310c69 |
};
|
|
Packit Service |
310c69 |
#define UDS_PARAMETERS_INITIALIZER { \
|
|
Packit Service |
310c69 |
.zone_count = 0, \
|
|
Packit Service |
310c69 |
.read_threads = 2, \
|
|
Packit Service |
310c69 |
.checkpoint_frequency = 0, \
|
|
Packit Service |
310c69 |
}
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Index statistics
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* These statistics capture the current index characteristics,
|
|
Packit Service |
310c69 |
* including resource usage.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
typedef struct udsIndexStats {
|
|
Packit Service |
310c69 |
/** The total number of chunk names stored in the index */
|
|
Packit Service |
310c69 |
uint64_t entriesIndexed;
|
|
Packit Service |
310c69 |
/** An estimate of the index's memory usage */
|
|
Packit Service |
310c69 |
uint64_t memoryUsed;
|
|
Packit Service |
310c69 |
/** The number of collisions recorded in the master index */
|
|
Packit Service |
310c69 |
uint64_t collisions;
|
|
Packit Service |
310c69 |
/** The number of entries discarded from the index since index startup */
|
|
Packit Service |
310c69 |
uint64_t entriesDiscarded;
|
|
Packit Service |
310c69 |
/** The number of checkpoints done this session */
|
|
Packit Service |
310c69 |
uint64_t checkpoints;
|
|
Packit Service |
310c69 |
} UdsIndexStats;
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Context statistics
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* These statistics capture a library context's characteristics either since
|
|
Packit Service |
310c69 |
* it was initialized or since its statistics were last reset, whichever
|
|
Packit Service |
310c69 |
* is more recent.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
typedef struct udsContextStats {
|
|
Packit Service |
310c69 |
/** The time at which context statistics were last fetched */
|
|
Packit Service |
310c69 |
time_t currentTime;
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The number of post calls since context statistics were last reset that
|
|
Packit Service |
310c69 |
* found an existing entry
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
uint64_t postsFound;
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The number of post calls since context statistics were last reset that
|
|
Packit Service |
310c69 |
* added an entry
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
uint64_t postsNotFound;
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The number of post calls since context statistics were last reset that
|
|
Packit Service |
310c69 |
* found an existing entry is current enough to only exist in memory and not
|
|
Packit Service |
310c69 |
* have been commited to disk yet.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
uint64_t inMemoryPostsFound;
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The number of post calls since context statistics were last reset that
|
|
Packit Service |
310c69 |
* found an existing entry in the dense portion of the index.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
uint64_t densePostsFound;
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The number of post calls since context statistics were last reset that
|
|
Packit Service |
310c69 |
* found an existing entry in the sparse portion of the index (if one
|
|
Packit Service |
310c69 |
* exists).
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
uint64_t sparsePostsFound;
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The number of update calls since context statistics were last reset that
|
|
Packit Service |
310c69 |
* updated an existing entry
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
uint64_t updatesFound;
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The number of update calls since context statistics were last reset that
|
|
Packit Service |
310c69 |
* added a new entry
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
uint64_t updatesNotFound;
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The number of delete requests since context statistics were last reset
|
|
Packit Service |
310c69 |
* that deleted an existing entry
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
uint64_t deletionsFound;
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The number of delete requests since context statistics were last reset
|
|
Packit Service |
310c69 |
* that did nothing.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
uint64_t deletionsNotFound;
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The number of query calls since context statistics were last reset that
|
|
Packit Service |
310c69 |
* found existing entry
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
uint64_t queriesFound;
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The number of query calls since context statistics were last reset that
|
|
Packit Service |
310c69 |
* did not find an entry
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
uint64_t queriesNotFound;
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The total number of library requests (the sum of posts, updates,
|
|
Packit Service |
310c69 |
* deletions, and queries) since context
|
|
Packit Service |
310c69 |
* statistics were last reset
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
uint64_t requests;
|
|
Packit Service |
310c69 |
} UdsContextStats;
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Initializes an index configuration.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [out] conf The new configuration
|
|
Packit Service |
310c69 |
* @param [in] memGB The maximum memory allocation, in GB
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return Either #UDS_SUCCESS or an error code
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
int udsInitializeConfiguration(UdsConfiguration *conf,
|
|
Packit Service |
310c69 |
UdsMemoryConfigSize memGB);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Sets or clears an index configuration's sparse indexing settings.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [in,out] conf The configuration to change
|
|
Packit Service |
310c69 |
* @param [in] sparse If true , request a sparse
|
|
Packit Service |
310c69 |
* index; if false , request
|
|
Packit Service |
310c69 |
* a default index.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
void udsConfigurationSetSparse(UdsConfiguration conf, bool sparse);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Tests whether an index configuration specifies sparse indexing.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [in] conf The configuration to check
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return Returns true if the configuration
|
|
Packit Service |
310c69 |
* is sparse, or false if not
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
bool udsConfigurationGetSparse(UdsConfiguration conf);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Sets an index configuration's nonce.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [in,out] conf The configuration to change
|
|
Packit Service |
310c69 |
* @param [in] nonce The 64 bit nonce.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
void udsConfigurationSetNonce(UdsConfiguration conf, UdsNonce nonce);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Gets an index configuration's nonce.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [in] conf The configuration to check
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return The 64 bit nonce.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
UdsNonce udsConfigurationGetNonce(UdsConfiguration conf);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Fetches a configuration's maximum memory allocation.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [in] conf The configuration to check
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return The amount of memory allocated, in GB
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
UdsMemoryConfigSize udsConfigurationGetMemory(UdsConfiguration conf);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Fetches a configuration's chapters per volume value.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [in] conf The configuration to check
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return The number of chapters per volume
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
unsigned int udsConfigurationGetChaptersPerVolume(UdsConfiguration conf);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Frees memory used by a configuration.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [in,out] conf The configuration for which memory is being freed
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
void udsFreeConfiguration(UdsConfiguration conf);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Compute the size required to store the index on persistent storage. This
|
|
Packit Service |
310c69 |
* size is valid for any index stored in a single file or on a single block
|
|
Packit Service |
310c69 |
* device. This size should be used when configuring a block device on which
|
|
Packit Service |
310c69 |
* to store an index.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [in] config A UdsConfiguration for an index.
|
|
Packit Service |
310c69 |
* @param [in] numCheckpoints The maximum number of checkpoints.
|
|
Packit Service |
310c69 |
* @param [out] indexSize The number of bytes required to store
|
|
Packit Service |
310c69 |
* the index.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return UDS_SUCCESS or an error code.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
int udsComputeIndexSize(const UdsConfiguration config,
|
|
Packit Service |
310c69 |
unsigned int numCheckpoints,
|
|
Packit Service |
310c69 |
uint64_t *indexSize);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Opens an index session.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* Creates a session for an index. #udsOpenIndex must be called before
|
|
Packit Service |
310c69 |
* the index can be used.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* Destroy the session with #udsDestroyIndexSession.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [out] session A pointer to the new session
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return Either #UDS_SUCCESS or an error code
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
int udsCreateIndexSession(struct uds_index_session **session);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Fetches the UDS library version.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return The library version
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
const char *udsGetVersion(void);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
#ifdef __KERNEL__
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The name argument to #udsOpenIndex is a text string that names the index.
|
|
Packit Service |
310c69 |
* The name should have the form "path", where path is the name of the block
|
|
Packit Service |
310c69 |
* device. The path should not contain white space. The names can optionally
|
|
Packit Service |
310c69 |
* contain size and/or offset options which give the number of bytes in the
|
|
Packit Service |
310c69 |
* index and the byte offset to the start of the index. For example, the name
|
|
Packit Service |
310c69 |
* "/dev/sda8 offset=409600 size=2048000000" is an index that is stored in
|
|
Packit Service |
310c69 |
* 2040000000 bytes of /dev/sda8 starting at byte 409600.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
#else
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* The name argument to #udsOpenIndex is a text string that names the index.
|
|
Packit Service |
310c69 |
* The name should have the form "path", where path is the name of the file or
|
|
Packit Service |
310c69 |
* block device. The path should not contain white space. The name can
|
|
Packit Service |
310c69 |
* optionally contain size and/or offset options which give the number of bytes
|
|
Packit Service |
310c69 |
* in the index and the byte offset to the start of the index. For example,
|
|
Packit Service |
310c69 |
* the name "/dev/sda8 offset=409600 size=2048000000" is an index that is
|
|
Packit Service |
310c69 |
* stored in 2040000000 bytes of /dev/sda8 starting at byte 409600.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
#endif
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Opens an index with an existing session. This operation will fail if the
|
|
Packit Service |
310c69 |
* index session is suspended, or if there is already an open index.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* The index should be closed with #udsCloseIndex.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param openType The type of open, which is one of #UDS_LOAD, #UDS_CREATE,
|
|
Packit Service |
310c69 |
* or #UDS_NO_REBUILD.
|
|
Packit Service |
310c69 |
* @param name The name of the index
|
|
Packit Service |
310c69 |
* @param params The index session parameters. If NULL, the default
|
|
Packit Service |
310c69 |
* session parameters will be used.
|
|
Packit Service |
310c69 |
* @param conf The index configuration
|
|
Packit Service |
310c69 |
* @param session The index session
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return Either #UDS_SUCCESS or an error code
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
int udsOpenIndex(UdsOpenIndexType openType,
|
|
Packit Service |
310c69 |
const char *name,
|
|
Packit Service |
310c69 |
const struct uds_parameters *params,
|
|
Packit Service |
310c69 |
UdsConfiguration conf,
|
|
Packit Service |
310c69 |
struct uds_index_session *session);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Waits until all callbacks for index operations are complete, and prevents
|
|
Packit Service |
310c69 |
* new index operations from starting. Index operations will return
|
|
Packit Service |
310c69 |
* UDS_SUSPENDED until #udsResumeIndexSession is called. Optionally saves all
|
|
Packit Service |
310c69 |
* index data before returning.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param session The session to suspend
|
|
Packit Service |
310c69 |
* @param save Whether to save index data
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return Either #UDS_SUCCESS or an error code
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
int udsSuspendIndexSession(struct uds_index_session *session, bool save);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Allows new index operations for an index, whether it was suspended or not.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param session The session to resume
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return Either #UDS_SUCCESS or an error code
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
int udsResumeIndexSession(struct uds_index_session *session);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Waits until all callbacks for index operations are complete.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [in] session The session to flush
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return Either #UDS_SUCCESS or an error code
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
int udsFlushIndexSession(struct uds_index_session *session);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Closes an index. This operation will fail if the index session is
|
|
Packit Service |
310c69 |
* suspended.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* Saves changes to the index so that #udsOpenIndex can re-open it.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [in] session The session containing the index to close
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return Either #UDS_SUCCESS or an error code
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
int udsCloseIndex(struct uds_index_session *session);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Destroys an index session.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* Saves changes to the index and closes the index if one is open.
|
|
Packit Service |
310c69 |
* Use #udsDestroyIndexSession for index sessions created by
|
|
Packit Service |
310c69 |
* #udsCreateIndexSession.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [in] session The session to destroy
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return Either #UDS_SUCCESS or an error code
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
int udsDestroyIndexSession(struct uds_index_session *session);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Returns the configuration for the given index session.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [in] session The session
|
|
Packit Service |
310c69 |
* @param [out] conf The index configuration
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return Either #UDS_SUCCESS or an error code
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
int udsGetIndexConfiguration(struct uds_index_session *session,
|
|
Packit Service |
310c69 |
UdsConfiguration *conf);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Fetches index statistics for the given index session.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [in] session The session
|
|
Packit Service |
310c69 |
* @param [out] stats The index statistics structure to fill
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return Either #UDS_SUCCESS or an error code
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
int udsGetIndexStats(struct uds_index_session *session, UdsIndexStats *stats);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Fetches index session statistics for the given index session.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param [in] session The session
|
|
Packit Service |
310c69 |
* @param [out] stats The context statistics structure to fill
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return Either #UDS_SUCCESS or an error code
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
int udsGetIndexSessionStats(struct uds_index_session *session,
|
|
Packit Service |
310c69 |
UdsContextStats *stats);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Convert an error code to a string.
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @param errnum The error code
|
|
Packit Service |
310c69 |
* @param buf The buffer to hold the error string
|
|
Packit Service |
310c69 |
* @param buflen The length of the buffer
|
|
Packit Service |
310c69 |
*
|
|
Packit Service |
310c69 |
* @return A pointer to buf
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
UDS_ATTR_WARN_UNUSED_RESULT
|
|
Packit Service |
310c69 |
const char *udsStringError(int errnum, char *buf, size_t buflen);
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
/**
|
|
Packit Service |
310c69 |
* Suggested buffer size for udsStringError.
|
|
Packit Service |
310c69 |
**/
|
|
Packit Service |
310c69 |
enum {
|
|
Packit Service |
310c69 |
UDS_STRING_ERROR_BUFSIZE = 128
|
|
Packit Service |
310c69 |
};
|
|
Packit Service |
310c69 |
|
|
Packit Service |
310c69 |
#endif /* UDS_H */
|