Index for Section 3

Alphabetical listing for L

Bottom of page

libinnhist(3)
NAME
  his - routines for managing INN history

SYNOPSIS
  #include <inn/history.h>

  struct history;

  struct histstats {	 int hitpos;	 int hitneg;	 int misses;	 int
  dne; };

  #define HIS_RDONLY ... #define HIS_RDWR ... #define HIS_CREAT ... #define
  HIS_ONDISK ... #define HIS_INCORE ... #define HIS_MMAP ...

  enum {     HISCTLG_PATH,     HISCTLS_PATH,	 HISCTLS_SYNCCOUNT,
  HISCTLS_NPAIRS,     HISCTLS_IGNOREOLD,     HISCTLS_STATINTERVAL };

  struct history *HISopen(const char *path, const char *method, int flags);

  bool HISclose(struct history *history);

  bool HISsync(struct history *history);

  void HISsetcache(struct history *history, size_t size);

  bool HISlookup(struct history *history, const char *key, time_t *arrived,
  time_t *posted, time_t *expires, TOKEN *token);

  bool HIScheck(struct history *history, const char *key);

  bool HISwrite(struct history *history, const char *key, time_t arrived,
  time_t posted, time_t expires, const TOKEN *token);

  bool HISremember(struct history *history, const char *key, time_t arrived);

  bool HISreplace(struct history *history, const char *key, time_t arrived,
  time_t posted, time_t expires, const TOKEN *token);

  bool HISexpire(struct history *history, const char *path, const char
  *reason, bool writing, void *cookie, time_t threshold, bool (*exists)(void
  *cookie, time_t arrived, time_t posted, time_t expires, const TOKEN
  *token));

  bool HISwalk(struct history *history, const char *reason, void *cookie,
  bool (*callback)(void *cookie, time_t arrived, time_t posted, time_t
  expires, const TOKEN *token));

  struct histstats HISstats(struct history *history);

  const char *HISerror(struct history *history);

  bool HISctl(struct history *history, int request, void *val);

DESCRIPTION
  These functions provide provide access to the INN history database. They
  maintain key/value pairs in an opaque database whilst providing for expiry
  of outdated information.

  The history structure is an opaque handle returned from HISopen.

  The HISopen function opens the history file designated by path using the
  mode flags using the specified method. flags may be HIS_RDONLY to indicate
  that read-only access to the history database is desired, or HIS_RDWR for
  read/write access. History methods are defined at build time; the history
  method currently available is "hisv6". On success a newly initialised
  history handle is returned, or NULL on failure.

  HIS_ONDISK, HIS_INCORE and HIS_MMAP may be logically ORed into flags to
  provide a hint to the underlying history manager as to how it should handle
  its data files; HIS_ONDISK indicates that the caller would like as much of
  the data to be kept on disk (and out of memory), HIS_INCORE indicates that
  the data files should be kept in main memory where possible and HIS_MMAP
  that the files should be mmap()ed into the processes address space.
  HIS_INCORE is typically used where a mass rebuild of the history database
  is being performed; the underlying history manager may assume that the
  caller will call HISsync() to sync the data files to disk.

  The HIS_CREAT flag indicates that the history database should be
  initialised as new; if any options which affect creation of the database
  need to be set an anonymous history handle should be created by calling
  HISopen with path set to NULL, any options set using HISctl, then the
  database opened by calling HISctl with HISCTLS_PATH.

  The HISclose function closes the handle history and deallocates any
  resources associated with it. It returns false on failure or true on
  success.

  The HISsync function synchronises any outstanding transactions associated
  with history to disk.

  HISsetcache associates a cache used for speeding up HIScheck with history.
  The cache will occupy approximately size bytes.

  HISlookup retrieves a token from history based on the passed key (normally
  the Message-ID). If no entry with an associated token can be found,
  HISlookup will return false. If a token is found arrived, expires, and
  posted are filled in with the message arrival, expiry, and posting times
  respectively (or zero, if the time component is not available), in addition
  to token being set to the retrieved token and a function return value of
  true. Any of arrived, expires, posted, or token may be NULL in which case
  that component is not returned to the caller, without affecting the return
  value.

  HIScheck checks the database history for key (normally the Message-ID); if
  key has previously been set via HISwrite, HIScheck returns true, else
  false.

  HISwrite writes a new entry to the database history associated with key.
  arrived, posted, and expired specify the arrival, posting, and expiry time
  respectively; posted and expired may be specifed as <= 0 in which case that
  component shall be treated as absent in the database. token is associated
  with the specified key. HISwrite returns true on success, or false on
  failure. The behaviour when key is not unique with respect to the existing
  entries in history is unspecified.

  HISremember writes a new entry to the database history associated with key,
  merely remembering that this key has been seen, together with its arrival
  time arrived. HISremember returns true on success, or false on failure. The
  behaviour when key is not unique with respect to the existing entries in
  history is unspecified.

  HISreplace replaces an existing entry in the database history, associated
  with key. arrived, posted, expired specify the arrival, posting and expiry
  time respectively; posted and expired may be specifed as <= 0 in which case
  that component shall be treated as absent in the database. token is
  associated with the specified key; if NULL then the history database merely
  remembers that this key has been seen, together with its arrival time.
  HISreplace returns true on success, or false on failure.

  HISexpire expires the history database associated with history, creating a
  new, replacement, database in the same location if path is NULL, or in path
  if not NULL; if path is not NULL then the replacement of the old history
  database with the new one is assumed to be performed out of band by the
  caller. The writing flag is normally passed as true, if you wish to inhibit
  writing of the new database (and so merely see the callbacks), writing may
  be set false.

  If the underlying history mechanism needs to pause the server, the reason
  string is used as the argument to the `ctlinnd pause' command, and as such
  the server should be reserved by the caller prior to calling HISexpire; if
  the caller wishes to inhibit pausing of the server, passing NULL will
  achieve this. If reason is not NULL, then on successful return from
  HISexpire the server will be left paused and the caller should unpause it.

  The history database is scanned and entries with an associated storage
  token are passed to the discrimination function exists.

  If exists() returns false it indicates that stored entity associated with
  token is no longer available (or no longer required), and therefore the
  associated history entry may be expired once it meets the threshold
  constraint. If exists() returns true the entry is kept as-is in the newly
  expired history database.

  The exists function is passed the arrival, posting and expiry times, in
  addition to the token associated with the entry. Note that posting and/or
  expiry may be zero, but that the token will never be NULL (such entries are
  handled solely via the threshold mechanism). The storage token passed to
  the discrimination function may updated if required (for example, as might
  be needed by a hierachical storage management implementation).

  Entries in the database with an arrival time less than threshold with no
  token associated with them are deleted from the database.

  The parameter cookie is passed to the discrimination function, and may be
  used for any purpose required by the caller.

  If the discrimination function attempts to access the underlying database
  (for read or write) during the callback, the behaviour is unspecified.

  HISwalk provides an iteration function for the specified history database.
  For every entry in the history database, callback is invoked, passing the
  cookie, arrival, posting, and expiry times, in addition to the token
  associated with the entry. If the callback() returns false the iteration is
  aborted and HISwalk returns false to the caller.

  To process the entire database in the presence of a running server, reason
  may be passed; if this argument is not NULL, it is used as an an argument
  to the `ctlinnd (reserve|pause|go)' commands. If reason is NULL and the
  server is running, the behaviour of HISwalk is undefined.

  If the callback function attempts to access the underlying database during
  the callback, the behaviour is unspecified.

  HISstats returns statistics on the history cache mechanism; given a handle
  history, the return value is a struct histstats detailing:

  "hitpos"
      The number of times an item was found directly in the cache and known
      to exist in the underlying history manager.

  "hitneg"
      The number of times an item was found directly in the cache and known
      not to exist in the underlying history manager.

  "misses"
      The number of times an item was not found directly in the cache, but on
      retrieval from the underlying history manager was found to exist.

  "dne"
      The number of times an item was not found directly in the cache, but on
      retrieval from the underlying history manager was found not to exist.

  Note that the history cache is only checked by HIScheck and only affected
  by HIScheck, HISwrite, HISremember and HISreplace. Following a call to
  HISstats the history statistics associated with history are cleared.

  HISerror returns a string describing the most recent error associated with
  history; the format and content of these strings is history manager
  dependent. Note that on setting an error, the history API will call the
  warn function from libinn(3).

  HISctl provides a control interface to the underlying history manager. The
  request argument determines the type of the request and the meaning of the
  val argument. The values for request are:

  "HISCTLG_PATH" (const char **)
      Get the base file path which the history handle represents. val should
      be a pointer to a location of type const char *.	The result must not
      later be passed to free(3).

  "HISCTLS_PATH" (const char *)
      Set the base file path which this history handle should use; typically
      this is used after an anonymous handle has been created using
      HISopen(NULL, ...). val should be a value of type const char * and will
      be copied before being stored internally.

  "HISCTLS_SYNCCOUNT" (size_t *)
      Set an upper bound on how many history operations may be pending in
      core before being synced to permanent storage; 0 indicates unlimited.
      val should be a pointer to a value of type size_t and will not be
      modified by the call.

  "HISCTLS_NPAIRS" (size_t *)
      Set a hint to the to the underlying history manager as to how many
      entries there are expected to be in the history database; 0 indicates
      that an automatic or default sizing should be made. val should be a
      pointer to a value of type size_t and will not be modified by the call.

  "HISCTLS_IGNOREOLD" (bool *)
      Instruct the underlying history manager to ignore existing database
      when creating new ones; typically this option may be set to true if the
      administrator believes that the existing history database is corrupt
      and that ignoring it may help. val should be a pointer to a value of
      type bool and will not be modified by the call.

  "HISCTLS_STATINTERVAL" (time_t *)
      For the history v6 and tagged hash managers, set the interval, in
      seconds, between stat(2)s of the history files checking for replaced
      files (as happens during expire); this option is typically used by
      nnrpd(8) like applications. val should be a pointer to a value of type
      time_t and will not be modified by the call.

HISTORY
  Written by Alex Kiernan <alexk@demon.net> for InterNetNews 2.4.0.

  $Id: libinnhist.3,v 1.7 2002/12/03 05:31:10 vinocur Exp $

Index for Section 3

Alphabetical listing for L

Top of page