Annotation of embedaddon/libpdel/sys/logfile.3, revision 1.1
1.1 ! misho 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.7 2004/06/02 17:24:38 archie 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.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to logfile.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / sys