1.\" Copyright (c) 2007 Joseph Koshy.  All rights reserved.
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions
5.\" are met:
6.\" 1. Redistributions of source code must retain the above copyright
7.\"    notice, this list of conditions and the following disclaimer.
8.\" 2. Redistributions in binary form must reproduce the above copyright
9.\"    notice, this list of conditions and the following disclaimer in the
10.\"    documentation and/or other materials provided with the distribution.
11.\"
12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
15.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
22.\" SUCH DAMAGE.
23.\"
24.\" $FreeBSD$
25.\"
26.Dd November 24, 2007
27.Dt PMC_CONFIGURE_LOGFILE 3
28.Os
29.Sh NAME
30.Nm pmc_configure_logfile ,
31.Nm pmc_flush_logfile ,
32.Nm pmc_writelog ,
33.Nm pmc_close_logfile
34.Nd log file management
35.Sh LIBRARY
36.Lb libpmc
37.Sh SYNOPSIS
38.In pmc.h
39.Ft int
40.Fn pmc_configure_logfile "int fd"
41.Ft int
42.Fn pmc_flush_logfile void
43.Ft int
44.Fn pmc_writelog "uint32_t userdata"
45.Ft int
46.Fn pmc_close_logfile void
47.Sh DESCRIPTION
48The functions manage logging of
49.Xr hwpmc 4
50events.
51.Pp
52Function
53.Fn pmc_configure_logfile
54is used to turn on and turn off logging.
55If argument
56.Fa fd
57is a valid file handle returned by a prior call to
58.Xr open 2
59or
60.Xr socket 2
61then performance events will be logged to the file corresponding
62to the specified handle.
63If the value of argument
64.Fa fd
65is -1 then logging will be stopped after any pending data is flushed.
66.Pp
67Function
68.Fn pmc_flush_logfile
69will force all log data queued inside the
70.Xr hwpmc 4
71driver to be written out.
72.Pp
73Function
74.Fn pmc_writelog
75will append a log entry containing the value of argument
76.Fa userdata
77to the log file.
78.Pp
79Function
80.Fn pmc_close_logfile
81will flush all pending log data and close
82.Xr hwpmc 4 Ns Ap s
83side of the stream.
84.Sh RETURN VALUES
85.Rv -std
86.Sh ERRORS
87A call to
88.Fn pmc_configure_logfile
89may fail with the following errors:
90.Bl -tag -width Er
91.It Bq Er EAGAIN
92The
93.Xr hwpmc 4
94driver was not able to create a helper process due to system limits
95being reached.
96.It Bq Er EBUSY
97Function
98.Fn pmc_configure_logfile
99was called with a log file already configured.
100.It Bq Er EINVAL
101Function
102.Fn pmc_configure_logfile
103was called with an argument of -1 without a log file being previously
104configured.
105.It Bq Er ENOMEM
106The system encountered a memory shortage when servicing this request.
107.El
108.Pp
109A call to
110.Fn pmc_flush_logfile
111may fail with the following errors:
112.Bl -tag -width Er
113.It Bq Er EINVAL
114Function
115.Fn pmc_flush_logfile
116was called without a log file being previously configured.
117.El
118.Pp
119A call to
120.Fn pmc_writelog
121may fail with the following errors:
122.Bl -tag -width Er
123.It Bq Er EINVAL
124Function
125.Fn pmc_writelog
126was called without a log file being previously configured.
127.It Bq Er ENOMEM
128The system encountered a memory shortage when servicing this
129request.
130.El
131.Sh SEE ALSO
132.Xr pmc 3 ,
133.Xr hwpmc 4
134