github.com/krum110487/go-htaccess@v0.0.0-20240316004156-60641c8e7598/tests/data/apache_2_2_34/include/apr_sdbm.h (about)

     1  /* Licensed to the Apache Software Foundation (ASF) under one or more
     2   * contributor license agreements.  See the NOTICE file distributed with
     3   * this work for additional information regarding copyright ownership.
     4   * The ASF licenses this file to You under the Apache License, Version 2.0
     5   * (the "License"); you may not use this file except in compliance with
     6   * the License.  You may obtain a copy of the License at
     7   *
     8   *     http://www.apache.org/licenses/LICENSE-2.0
     9   *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  
    17  /*
    18   * sdbm - ndbm work-alike hashed database library
    19   * based on Per-Ake Larson's Dynamic Hashing algorithms. BIT 18 (1978).
    20   * author: oz@nexus.yorku.ca
    21   * status: ex-public domain
    22   */
    23  
    24  #ifndef APR_SDBM_H
    25  #define APR_SDBM_H
    26  
    27  #include "apu.h"
    28  #include "apr_errno.h"
    29  #include "apr_file_io.h"   /* for apr_fileperms_t */
    30  
    31  /** 
    32   * @file apr_sdbm.h
    33   * @brief apr-util SDBM library
    34   */
    35  /**
    36   * @defgroup APR_Util_DBM_SDBM SDBM library
    37   * @ingroup APR_Util_DBM
    38   * @{
    39   */
    40  
    41  /**
    42   * Structure for referencing an sdbm
    43   */
    44  typedef struct apr_sdbm_t apr_sdbm_t;
    45  
    46  /**
    47   * Structure for referencing the datum record within an sdbm
    48   */
    49  typedef struct {
    50      /** pointer to the data stored/retrieved */
    51      char *dptr;
    52      /** size of data */
    53      /* apr_ssize_t for release 2.0??? */
    54      int dsize;
    55  } apr_sdbm_datum_t;
    56  
    57  /* The extensions used for the database files */
    58  /** SDBM Directory file extension */
    59  #define APR_SDBM_DIRFEXT	".dir"
    60  /** SDBM page file extension */
    61  #define APR_SDBM_PAGFEXT	".pag"
    62  
    63  /* flags to sdbm_store */
    64  #define APR_SDBM_INSERT     0   /**< Insert */
    65  #define APR_SDBM_REPLACE    1   /**< Replace */
    66  #define APR_SDBM_INSERTDUP  2   /**< Insert with duplicates */
    67  
    68  /**
    69   * Open an sdbm database by file name
    70   * @param db The newly opened database
    71   * @param name The sdbm file to open
    72   * @param mode The flag values (APR_READ and APR_BINARY flags are implicit)
    73   * <PRE>
    74   *           APR_WRITE          open for read-write access
    75   *           APR_CREATE         create the sdbm if it does not exist
    76   *           APR_TRUNCATE       empty the contents of the sdbm
    77   *           APR_EXCL           fail for APR_CREATE if the file exists
    78   *           APR_DELONCLOSE     delete the sdbm when closed
    79   *           APR_SHARELOCK      support locking across process/machines
    80   * </PRE>
    81   * @param perms Permissions to apply to if created
    82   * @param p The pool to use when creating the sdbm
    83   * @remark The sdbm name is not a true file name, as sdbm appends suffixes 
    84   * for seperate data and index files.
    85   */
    86  APU_DECLARE(apr_status_t) apr_sdbm_open(apr_sdbm_t **db, const char *name, 
    87                                          apr_int32_t mode, 
    88                                          apr_fileperms_t perms, apr_pool_t *p);
    89  
    90  /**
    91   * Close an sdbm file previously opened by apr_sdbm_open
    92   * @param db The database to close
    93   */
    94  APU_DECLARE(apr_status_t) apr_sdbm_close(apr_sdbm_t *db);
    95  
    96  /**
    97   * Lock an sdbm database for concurency of multiple operations
    98   * @param db The database to lock
    99   * @param type The lock type
   100   * <PRE>
   101   *           APR_FLOCK_SHARED
   102   *           APR_FLOCK_EXCLUSIVE
   103   * </PRE>
   104   * @remark Calls to apr_sdbm_lock may be nested.  All apr_sdbm functions
   105   * perform implicit locking.  Since an APR_FLOCK_SHARED lock cannot be 
   106   * portably promoted to an APR_FLOCK_EXCLUSIVE lock, apr_sdbm_store and 
   107   * apr_sdbm_delete calls will fail if an APR_FLOCK_SHARED lock is held.
   108   * The apr_sdbm_lock call requires the database to be opened with the
   109   * APR_SHARELOCK mode value.
   110   */
   111  APU_DECLARE(apr_status_t) apr_sdbm_lock(apr_sdbm_t *db, int type);
   112  
   113  /**
   114   * Release an sdbm lock previously aquired by apr_sdbm_lock
   115   * @param db The database to unlock
   116   */
   117  APU_DECLARE(apr_status_t) apr_sdbm_unlock(apr_sdbm_t *db);
   118  
   119  /**
   120   * Fetch an sdbm record value by key
   121   * @param db The database 
   122   * @param value The value datum retrieved for this record
   123   * @param key The key datum to find this record
   124   */
   125  APU_DECLARE(apr_status_t) apr_sdbm_fetch(apr_sdbm_t *db, 
   126                                           apr_sdbm_datum_t *value, 
   127                                           apr_sdbm_datum_t key);
   128  
   129  /**
   130   * Store an sdbm record value by key
   131   * @param db The database 
   132   * @param key The key datum to store this record by
   133   * @param value The value datum to store in this record
   134   * @param opt The method used to store the record
   135   * <PRE>
   136   *           APR_SDBM_INSERT     return an error if the record exists
   137   *           APR_SDBM_REPLACE    overwrite any existing record for key
   138   * </PRE>
   139   */
   140  APU_DECLARE(apr_status_t) apr_sdbm_store(apr_sdbm_t *db, apr_sdbm_datum_t key,
   141                                           apr_sdbm_datum_t value, int opt);
   142  
   143  /**
   144   * Delete an sdbm record value by key
   145   * @param db The database 
   146   * @param key The key datum of the record to delete
   147   * @remark It is not an error to delete a non-existent record.
   148   */
   149  APU_DECLARE(apr_status_t) apr_sdbm_delete(apr_sdbm_t *db, 
   150                                            const apr_sdbm_datum_t key);
   151  
   152  /**
   153   * Retrieve the first record key from a dbm
   154   * @param db The database 
   155   * @param key The key datum of the first record
   156   * @remark The keys returned are not ordered.  To traverse the list of keys
   157   * for an sdbm opened with APR_SHARELOCK, the caller must use apr_sdbm_lock
   158   * prior to retrieving the first record, and hold the lock until after the
   159   * last call to apr_sdbm_nextkey.
   160   */
   161  APU_DECLARE(apr_status_t) apr_sdbm_firstkey(apr_sdbm_t *db, apr_sdbm_datum_t *key);
   162  
   163  /**
   164   * Retrieve the next record key from an sdbm
   165   * @param db The database 
   166   * @param key The key datum of the next record
   167   */
   168  APU_DECLARE(apr_status_t) apr_sdbm_nextkey(apr_sdbm_t *db, apr_sdbm_datum_t *key);
   169  
   170  /**
   171   * Returns true if the sdbm database opened for read-only access
   172   * @param db The database to test
   173   */
   174  APU_DECLARE(int) apr_sdbm_rdonly(apr_sdbm_t *db);
   175  /** @} */
   176  #endif /* APR_SDBM_H */