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.Dd November 24, 2007 25.Dt PMC_CONFIGURE_LOGFILE 3 26.Os 27.Sh NAME 28.Nm pmc_configure_logfile , 29.Nm pmc_flush_logfile , 30.Nm pmc_writelog , 31.Nm pmc_close_logfile 32.Nd log file management 33.Sh LIBRARY 34.Lb libpmc 35.Sh SYNOPSIS 36.In pmc.h 37.Ft int 38.Fn pmc_configure_logfile "int fd" 39.Ft int 40.Fn pmc_flush_logfile void 41.Ft int 42.Fn pmc_writelog "uint32_t userdata" 43.Ft int 44.Fn pmc_close_logfile void 45.Sh DESCRIPTION 46The functions manage logging of 47.Xr hwpmc 4 48events. 49.Pp 50Function 51.Fn pmc_configure_logfile 52is used to turn on and turn off logging. 53If argument 54.Fa fd 55is a valid file handle returned by a prior call to 56.Xr open 2 57or 58.Xr socket 2 59then performance events will be logged to the file corresponding 60to the specified handle. 61If the value of argument 62.Fa fd 63is -1 then logging will be stopped after any pending data is flushed. 64.Pp 65Function 66.Fn pmc_flush_logfile 67will force all log data queued inside the 68.Xr hwpmc 4 69driver to be written out. 70.Pp 71Function 72.Fn pmc_writelog 73will append a log entry containing the value of argument 74.Fa userdata 75to the log file. 76.Pp 77Function 78.Fn pmc_close_logfile 79will flush all pending log data and close 80.Xr hwpmc 4 Ns Ap s 81side of the stream. 82.Sh RETURN VALUES 83.Rv -std 84.Sh ERRORS 85A call to 86.Fn pmc_configure_logfile 87may fail with the following errors: 88.Bl -tag -width Er 89.It Bq Er EAGAIN 90The 91.Xr hwpmc 4 92driver was not able to create a helper process due to system limits 93being reached. 94.It Bq Er EBUSY 95Function 96.Fn pmc_configure_logfile 97was called with a log file already configured. 98.It Bq Er EINVAL 99Function 100.Fn pmc_configure_logfile 101was called with an argument of -1 without a log file being previously 102configured. 103.It Bq Er ENOMEM 104The system encountered a memory shortage when servicing this request. 105.El 106.Pp 107A call to 108.Fn pmc_flush_logfile 109may fail with the following errors: 110.Bl -tag -width Er 111.It Bq Er EINVAL 112Function 113.Fn pmc_flush_logfile 114was called without a log file being previously configured. 115.El 116.Pp 117A call to 118.Fn pmc_writelog 119may fail with the following errors: 120.Bl -tag -width Er 121.It Bq Er EINVAL 122Function 123.Fn pmc_writelog 124was called without a log file being previously configured. 125.It Bq Er ENOMEM 126The system encountered a memory shortage when servicing this 127request. 128.El 129.Sh SEE ALSO 130.Xr pmc 3 , 131.Xr hwpmc 4 132