Return to logfile.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / sys

libpdel

    1: .\" Copyright (c) 2001-2002 Packet Design, LLC.
    2: .\" All rights reserved.
    3: .\" 
    4: .\" Subject to the following obligations and disclaimer of warranty,
    5: .\" use and redistribution of this software, in source or object code
    6: .\" forms, with or without modifications are expressly permitted by
    7: .\" Packet Design; provided, however, that:
    8: .\" 
    9: .\"    (i)  Any and all reproductions of the source or object code
   10: .\"         must include the copyright notice above and the following
   11: .\"         disclaimer of warranties; and
   12: .\"    (ii) No rights are granted, in any manner or form, to use
   13: .\"         Packet Design trademarks, including the mark "PACKET DESIGN"
   14: .\"         on advertising, endorsements, or otherwise except as such
   15: .\"         appears in the above copyright notice or in the software.
   16: .\" 
   17: .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
   18: .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
   19: .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
   20: .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
   21: .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
   22: .\" OR NON-INFRINGEMENT.  PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
   23: .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
   24: .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
   25: .\" RELIABILITY OR OTHERWISE.  IN NO EVENT SHALL PACKET DESIGN BE
   26: .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
   27: .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
   28: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
   29: .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
   30: .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
   31: .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   32: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
   33: .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
   34: .\" THE POSSIBILITY OF SUCH DAMAGE.
   35: .\"
   36: .\" Author: Archie Cobbs <archie@freebsd.org>
   37: .\"
   38: .\" $Id: logfile.3,v 1.1.1.1 2012/02/21 23:25:53 misho Exp $
   39: .\"
   40: .Dd April 22, 2002
   41: .Dt LOGFILE 3
   42: .Os
   43: .Sh NAME
   44: .Nm logfile
   45: .Nd circular log files
   46: .Sh LIBRARY
   47: PDEL Library (libpdel, \-lpdel)
   48: .Sh SYNOPSIS
   49: .In sys/types.h
   50: .In pdel/sys/logfile.h
   51: .Ft "struct logfile *"
   52: .Fn logfile_open "const char *path" "int flags" "u_int32_t maxent" "u_int32_t maxdata"
   53: .Ft void
   54: .Fn logfile_close "struct logfile **lfp"
   55: .Ft u_int32_t
   56: .Fn logfile_num_entries "struct logfile *lf"
   57: .Ft "const void *"
   58: .Fn logfile_get "struct logfile *lf" "int which" "int *lenp"
   59: .Ft int
   60: .Fn logfile_put "struct logfile *lf" "const void *data" "int len"
   61: .Ft void
   62: .Fn logfile_trim "struct logfile *lf" "int num"
   63: .Ft void
   64: .Fn logfile_sync "struct logfile *lf"
   65: .Sh DESCRIPTION
   66: These functions provide support for circular log files.
   67: A
   68: .Nm logfile
   69: file contains the most recently added entries, where an entry
   70: is any opaque chunk of data supplied by the application.
   71: When the file becomes full, new entries overwrite the oldest
   72: entries in a circular fashion.
   73: .Pp
   74: Each
   75: .Nm logfile
   76: file has a fixed size and is accessed using
   77: .Xr mmap 2
   78: for efficiency.
   79: .Pp
   80: .Fn logfile_open
   81: opens the log file with pathname
   82: .Fa path .
   83: .Fa flags
   84: may be equal to zero,
   85: .Dv O_SHLOCK ,
   86: or
   87: .Dv O_EXLOCK
   88: for locking purposes
   89: (see
   90: .Xr open 2
   91: for details).
   92: If the file is locked,
   93: .Fn logfile_open
   94: does not block, but instead returns
   95: .Dv NULL
   96: immediately with
   97: .Va errno
   98: set to
   99: .Er EWOULDBLOCK .
  100: .Pp
  101: If the named file exists, it must be a valid
  102: .Nm logfile
  103: file and
  104: .Fa maxent
  105: and
  106: .Fa maxdata
  107: are ignored.
  108: Otherwise, it is created using those parameters:
  109: .Fa maxent
  110: limits the total number of entries that the file may contain, and
  111: .Fa maxdata
  112: limit the total amount of entry data (in bytes) that the file
  113: may contain.
  114: When full, the file's ultimate size will be approximately
  115: .Fa maxdata
  116: + (8 *
  117: .Fa maxent )
  118: + 20.
  119: .Pp
  120: The 
  121: .Fa path
  122: may be
  123: .Dv NULL ,
  124: in which case the logfile is not stored in the file system and
  125: therefore is not persistent.
  126: .Pp
  127: .Fn logfile_close
  128: closes a log file previously opened using
  129: .Fn logfile_open .
  130: Upon return,
  131: .Fa "*lfp"
  132: will be set to
  133: .Dv NULL .
  134: If
  135: .Fa "*lfp"
  136: is already equal to
  137: .Dv NULL
  138: when
  139: .Fn logfile_close
  140: is invoked, nothing happens.
  141: .Pp
  142: .Fn logfile_num_entries
  143: returns the number of valid entries contained in a log file.
  144: .Pp
  145: .Fn logfile_get
  146: retrieves an entry from a log file.
  147: .Fa which
  148: must be a negative number: -1 is the most recently added entry,
  149: -2 is the second most recently added, etc.
  150: If
  151: .Fa "lenp"
  152: is not equal to
  153: .Dv NULL ,
  154: then
  155: .Fa "*lenp"
  156: is set to the length of the entry.
  157: Entries returned by
  158: .Fn logfile_get
  159: are contiguous and suitably aligned for any type.
  160: The caller should not free the returned pointer.
  161: .Pp
  162: .Fn logfile_put
  163: adds a new entry to a log file.
  164: The entry is pointed to by
  165: .Fa data
  166: and has length
  167: .Fa len .
  168: .Pp
  169: .Fn logfile_trim
  170: discards the oldest entries in a log file as necessary to make
  171: the total number of entries be at most
  172: .Fa num .
  173: .Pp
  174: .Fn logfile_sync
  175: synchronously flushes any unwritten entries to permanent storage.
  176: .Pp
  177: Each
  178: .Nm logfile
  179: object maintains an internal mutex lock.
  180: The functions
  181: .Fn logfile_num_entries ,
  182: .Fn logfile_get ,
  183: .Fn logfile_put ,
  184: .Fn logfile_trim ,
  185: and
  186: .Fn logfile_sync
  187: may be safely called simultaneously from different threads.
  188: .Sh RETURN VALUES
  189: .Fn logfile_open
  190: and
  191: .Fn logfile_get
  192: return
  193: .Dv NULL
  194: to indicate an error.
  195: .Fn logfile_put
  196: returns -1 to indicate an error.
  197: In all error cases,
  198: .Va errno
  199: is set accordingly.
  200: .Sh SEE ALSO
  201: .Xr open 2 ,
  202: .Xr alog 3 ,
  203: .Xr libpdel 3 ,
  204: .Xr typed_mem 3
  205: .Sh HISTORY
  206: The PDEL library was developed at Packet Design, LLC.
  207: .Dv "http://www.packetdesign.com/"
  208: .Sh AUTHORS
  209: .An Archie Cobbs Aq archie@freebsd.org
  210: .Sh BUGS
  211: Meta information is stored in the logfile in host order.
  212: Therefore,
  213: .Nm logfile
  214: files are not portable.