Annotation of embedaddon/libpdel/sys/logfile.3, revision 1.1.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