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