Na}{

File Content: `libtraceevent-kbuffer-read.html`

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 9.1.0" />
<title>libtraceevent(3)</title>
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */

/* Default font. */
body {
  font-family: Georgia,serif;
}

/* Title font. */
h1, h2, h3, h4, h5, h6,
div.title, caption.title,
thead, p.table.header,
#toctitle,
#author, #revnumber, #revdate, #revremark,
#footer {
  font-family: Arial,Helvetica,sans-serif;
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}
h5 {
  font-size: 1.0em;
}

div.sectionbody {
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}
ul > li     { color: #aaa; }
ul > li > * { color: black; }

.monospaced, code, pre {
  font-family: "Courier New", Courier, monospace;
  font-size: inherit;
  color: navy;
  padding: 0;
  margin: 0;
}
pre {
  white-space: pre-wrap;
}

#author {
  color: #527bbd;
  font-weight: bold;
  font-size: 1.1em;
}
#email {
}
#revnumber, #revdate, #revremark {
}

#footer {
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid #dddddd;
  border-left: 4px solid #f0f0f0;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid #dddddd;
  border-left: 5px solid #f0f0f0;
  background: #f8f8f8;
  padding: 0.5em;
}

div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #f0f0f0;
  color: #888;
}

div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock > pre.content {
  font-family: inherit;
  font-size: inherit;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 3px solid #dddddd;
}

div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; vertical-align: text-bottom; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}

div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

.footnote, .footnoteref {
  font-size: 0.8em;
}

span.footnote, span.footnoteref {
  vertical-align: super;
}

#footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
}

#footnotes div.footnote {
  margin: 0 0 5px 0;
}

#footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
}

div.colist td {
  padding-right: 0.5em;
  padding-bottom: 0.3em;
  vertical-align: top;
}
div.colist td img {
  margin-top: 0.3em;
}

@media print {
  #footer-badges { display: none; }
}

#toc {
  margin-bottom: 2.5em;
}

#toctitle {
  color: #527bbd;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}

span.aqua { color: aqua; }
span.black { color: black; }
span.blue { color: blue; }
span.fuchsia { color: fuchsia; }
span.gray { color: gray; }
span.green { color: green; }
span.lime { color: lime; }
span.maroon { color: maroon; }
span.navy { color: navy; }
span.olive { color: olive; }
span.purple { color: purple; }
span.red { color: red; }
span.silver { color: silver; }
span.teal { color: teal; }
span.white { color: white; }
span.yellow { color: yellow; }

span.aqua-background { background: aqua; }
span.black-background { background: black; }
span.blue-background { background: blue; }
span.fuchsia-background { background: fuchsia; }
span.gray-background { background: gray; }
span.green-background { background: green; }
span.lime-background { background: lime; }
span.maroon-background { background: maroon; }
span.navy-background { background: navy; }
span.olive-background { background: olive; }
span.purple-background { background: purple; }
span.red-background { background: red; }
span.silver-background { background: silver; }
span.teal-background { background: teal; }
span.white-background { background: white; }
span.yellow-background { background: yellow; }

span.big { font-size: 2em; }
span.small { font-size: 0.6em; }

span.underline { text-decoration: underline; }
span.overline { text-decoration: overline; }
span.line-through { text-decoration: line-through; }

div.unbreakable { page-break-inside: avoid; }


/*
 * xhtml11 specific
 *
 * */

div.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
div.tableblock > table {
  border: 3px solid #527bbd;
}
thead, p.table.header {
  font-weight: bold;
  color: #527bbd;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overridden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


/*
 * html5 specific
 *
 * */

table.tableblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
}
thead, p.tableblock.header {
  font-weight: bold;
  color: #527bbd;
}
p.tableblock {
  margin-top: 0;
}
table.tableblock {
  border-width: 3px;
  border-spacing: 0px;
  border-style: solid;
  border-color: #527bbd;
  border-collapse: collapse;
}
th.tableblock, td.tableblock {
  border-width: 1px;
  padding: 4px;
  border-style: solid;
  border-color: #527bbd;
}

table.tableblock.frame-topbot {
  border-left-style: hidden;
  border-right-style: hidden;
}
table.tableblock.frame-sides {
  border-top-style: hidden;
  border-bottom-style: hidden;
}
table.tableblock.frame-none {
  border-style: hidden;
}

th.tableblock.halign-left, td.tableblock.halign-left {
  text-align: left;
}
th.tableblock.halign-center, td.tableblock.halign-center {
  text-align: center;
}
th.tableblock.halign-right, td.tableblock.halign-right {
  text-align: right;
}

th.tableblock.valign-top, td.tableblock.valign-top {
  vertical-align: top;
}
th.tableblock.valign-middle, td.tableblock.valign-middle {
  vertical-align: middle;
}
th.tableblock.valign-bottom, td.tableblock.valign-bottom {
  vertical-align: bottom;
}


/*
 * manpage specific
 *
 * */

body.manpage h1 {
  padding-top: 0.5em;
  padding-bottom: 0.5em;
  border-top: 2px solid silver;
  border-bottom: 2px solid silver;
}
body.manpage h2 {
  border-style: none;
}
body.manpage div.sectionbody {
  margin-left: 3em;
}

@media print {
  body.manpage div#toc { display: none; }
}


</style>
<script type="text/javascript">
/*<![CDATA[*/
var asciidoc = {  // Namespace.

/////////////////////////////////////////////////////////////////////
// Table Of Contents generator
/////////////////////////////////////////////////////////////////////

/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, 2006, 2009. License: GPL */

// toclevels = 1..4.
toc: function (toclevels) {

  function getText(el) {
    var text = "";
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
        text += i.data;
      else if (i.firstChild != null)
        text += getText(i);
    }
    return text;
  }

  function TocEntry(el, text, toclevel) {
    this.element = el;
    this.text = text;
    this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
    var result = new Array;
    var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
    // Function that scans the DOM tree for header elements (the DOM2
    // nodeIterator API would be a better technique but not supported by all
    // browsers).
    var iterate = function (el) {
      for (var i = el.firstChild; i != null; i = i.nextSibling) {
        if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
          var mo = re.exec(i.tagName);
          if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
            result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
          }
          iterate(i);
        }
      }
    }
    iterate(el);
    return result;
  }

  var toc = document.getElementById("toc");
  if (!toc) {
    return;
  }

  // Delete existing TOC entries in case we're reloading the TOC.
  var tocEntriesToRemove = [];
  var i;
  for (i = 0; i < toc.childNodes.length; i++) {
    var entry = toc.childNodes[i];
    if (entry.nodeName.toLowerCase() == 'div'
     && entry.getAttribute("class")
     && entry.getAttribute("class").match(/^toclevel/))
      tocEntriesToRemove.push(entry);
  }
  for (i = 0; i < tocEntriesToRemove.length; i++) {
    toc.removeChild(tocEntriesToRemove[i]);
  }

  // Rebuild TOC entries.
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "_toc_" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    toc.parentNode.removeChild(toc);
},


/////////////////////////////////////////////////////////////////////
// Footnotes generator
/////////////////////////////////////////////////////////////////////

/* Based on footnote generation code from:
 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 */

footnotes: function () {
  // Delete existing footnote entries in case we're reloading the footnodes.
  var i;
  var noteholder = document.getElementById("footnotes");
  if (!noteholder) {
    return;
  }
  var entriesToRemove = [];
  for (i = 0; i < noteholder.childNodes.length; i++) {
    var entry = noteholder.childNodes[i];
    if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
      entriesToRemove.push(entry);
  }
  for (i = 0; i < entriesToRemove.length; i++) {
    noteholder.removeChild(entriesToRemove[i]);
  }

  // Rebuild footnote entries.
  var cont = document.getElementById("content");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
    if (spans[i].className == "footnote") {
      n++;
      var note = spans[i].getAttribute("data-note");
      if (!note) {
        // Use [\s\S] in place of . so multi-line matches work.
        // Because JavaScript has no s (dotall) regex flag.
        note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
        spans[i].innerHTML =
          "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
        spans[i].setAttribute("data-note", note);
      }
      noteholder.innerHTML +=
        "<div class='footnote' id='_footnote_" + n + "'>" +
        "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
        n + "</a>. " + note + "</div>";
      var id =spans[i].getAttribute("id");
      if (id != null) refs["#"+id] = n;
    }
  }
  if (n == 0)
    noteholder.parentNode.removeChild(noteholder);
  else {
    // Process footnoterefs.
    for (i=0; i<spans.length; i++) {
      if (spans[i].className == "footnoteref") {
        var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
        href = href.match(/#.*/)[0];  // Because IE return full URL.
        n = refs[href];
        spans[i].innerHTML =
          "[<a href='#_footnote_" + n +
          "' title='View footnote' class='footnote'>" + n + "</a>]";
      }
    }
  }
},

install: function(toclevels) {
  var timerId;

  function reinstall() {
    asciidoc.footnotes();
    if (toclevels) {
      asciidoc.toc(toclevels);
    }
  }

  function reinstallAndRemoveTimer() {
    clearInterval(timerId);
    reinstall();
  }

  timerId = setInterval(reinstall, 500);
  if (document.addEventListener)
    document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
  else
    window.onload = reinstallAndRemoveTimer;
}

}
asciidoc.install();
/*]]>*/
</script>
</head>
<body class="manpage">
<div id="header">
<h1>
libtraceevent(3) Manual Page
</h1>
<h2>NAME</h2>
<div class="sectionbody">
<p>kbuffer_read_event, kbuffer_next_event, kbuffer_missed_events, kbuffer_event_size, kbuffer_curr_size, kbuffer_curr_offset, kbuffer_curr_index, kbuffer_read_buffer -
   Functions to read through the kbuffer sub buffer.
</p>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="_synopsis">SYNOPSIS</h2>
<div class="sectionbody">
<div class="verseblock">
<pre class="content"><strong>#include &lt;kbuffer.h&gt;</strong>

void *<strong>kbuffer_read_event</strong>(struct kbuffer *<em>kbuf</em>, unsigned long long *<em>ts</em>);
void *<strong>kbuffer_next_event</strong>(struct kbuffer *<em>kbuf</em>, unsigned long long *<em>ts</em>);
void *<strong>kbuffer_read_at_offset</strong>(struct kbuffer *<em>kbuf</em>, int <em>offset</em>, unsigned long long *<em>ts</em>);
int <strong>kbuffer_missed_events</strong>(struct kbuffer *<em>kbuf</em>);
int <strong>kbuffer_event_size</strong>(struct kbuffer *<em>kbuf</em>);
int <strong>kbuffer_curr_size</strong>(struct kbuffer *<em>kbuf</em>);
int <strong>kbuffer_curr_offset</strong>(struct kbuffer *<em>kbuf</em>);
int <strong>kbuffer_curr_index</strong>(struct kbuffer *<em>kbuf</em>);
int <strong>kbuffer_read_buffer</strong>(struct kbuffer *<em>kbuf</em>, void *<em>buffer</em>, int <em>len</em>);</pre>
<div class="attribution">
</div></div>
</div>
</div>
<div class="sect1">
<h2 id="_description">DESCRIPTION</h2>
<div class="sectionbody">
<div class="paragraph"><p>The function <strong>kbuffer_read_event()</strong> reads the next event in the <em>kbuf</em> descriptor
and if <em>ts</em> is non NULL, will place its timestamp into it. This does not modify the <em>kbuf</em>
descriptor, and calling this function mulitple times will return the same result.</p></div>
<div class="paragraph"><p>The function <strong>kbuffer_next_event()</strong> will return the next event in the <em>kbuf</em> descriptor.
It will also set the <em>ts</em> to the timestamp of the returned event. NULL is returned
if there are no more events and <em>ts</em> will be undefined. Note, if this is called directly
after a <strong>kbuffer_load_subbuffer()</strong> then it will likely give an unexpected result, as it
will return the second event and not the first event. Usually this function is only used
to move to the next event and to know if there&#8217;s any more events to read, and
<strong>kbuffer_read_event()</strong> is always called first.</p></div>
<div class="paragraph"><p>The function <strong>kbuffer_read_at_offset()</strong> returns the event located at a given <em>offset</em> from
the beginning of the sub-buffer. This offset can be retrieved by <strong>kbuffer_curr_offset()</strong>.
If <em>ts</em> points to an unsigned long long, then it will be set to the event at the given
offset&#8217;s timestamp.</p></div>
<div class="paragraph"><p>If the sub-buffer had missed events before it, then <strong>kbuffer_missed_events()</strong> will return
the non zero. If it returns -1, that means there were missed events, but the exact number
of missed events is unknown. If it returns a positive number, then the number of missed events
is the return value.</p></div>
<div class="paragraph"><p>The <strong>kbuffer_event_size()</strong> function returns the size of the data portion of the current event
(the one that would be returned by <strong>kbuffer_read_event()</strong>.</p></div>
<div class="paragraph"><p>The <strong>kbuffer_curr_size()</strong> function returns the entire record size of the current event
(the one that would be returned by <strong>kbuffer_read_event()</strong>. The difference here is that the
return value includes the size of the event record meta data that is not part of what
is returned by <strong>kbuffer_read_event()</strong>.</p></div>
<div class="paragraph"><p>The <strong>kbuffer_curr_offset()</strong> function returns the offset from the beginning of the sub-buffer
of where the current event&#8217;s meta data for the record begins. The first event will
not be at offset zero. This offset can be used to retrieve the event with
<strong>kbuffer_read_at_offset()</strong>.</p></div>
<div class="paragraph"><p>The <strong>kbuffer_curr_index()</strong> function returns the index from the beginning of the data
portion of the sub-buffer where the current evnet&#8217;s meta data is located.
The first event will likely be zero, but may not be if there&#8217;s a timestamp attached to it.</p></div>
<div class="paragraph"><p>The <strong>kbuffer_read_buffer()</strong> function will fill the given <em>buffer</em> from the <em>kbuf</em> the same
way the kernel would do a read system call. That is, if the length <em>len</em> is less than the
sub buffer size, or the kbuffer current index is non-zero, it will start copying from the
<em>kbuf</em> current event and create <em>buffer</em> as a new sub buffer (with a timestamp
and commit header) with that event that was found and including all events after that can
fit within <em>len</em>. The <em>len</em> must include the size of the sub buffer header as well as the
events to include. That is, <em>len</em> is the allocate size of <em>buffer</em> that can be filled.
The return from this function is the index of the end of the last event that was added.
If there are no more events then zero is returned, and if the buffer can not
copy any events because <em>len</em> was too small, then -1 is returned.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_return_value">RETURN VALUE</h2>
<div class="sectionbody">
<div class="paragraph"><p><strong>kbuffer_read_event()</strong> returns the event that the <em>kbuf</em> descriptor is currently at,
or NULL if the last event was passed (by <strong>kbuffer_next_event()</strong>).</p></div>
<div class="paragraph"><p><strong>kbuffer_next_event()</strong> returns the next event after the current event or NULL if there
are no more events.</p></div>
<div class="paragraph"><p><strong>kbuffer_read_at_offset()</strong> returns the event at a given <em>offset</em> from the start of
the sub-buffer stored in <em>kbuf</em>, or NULL if there exists no event. Note, <em>offset</em>
only needs to be an offset that lands on the record, or is at the start of it. It does
not need to be exactly at the beginning of the record.</p></div>
<div class="paragraph"><p><strong>kbuffer_missed_events()</strong> returns 0 if there were no missed events before loaded sub-buffer.
Returns -1 if there were an unknown number of missed events, or if the number of missed events
is known, that number will be returned.</p></div>
<div class="paragraph"><p><strong>kbuffer_event_size()</strong> returns the size of the data payload of the current event of <em>kbuf</em>.</p></div>
<div class="paragraph"><p><strong>kbuffer_curr_size()</strong> returns the size of the entire record of the current event of <em>kbuf</em>.
This includes the size of the meta data for that record.</p></div>
<div class="paragraph"><p><strong>kbuf_curr_offset()</strong> returns the offset of the current record from the beginning of the <em>kbuf</em>
sub-buffer.</p></div>
<div class="paragraph"><p><strong>kbuf_curr_index()</strong> returns the index of the current record from the beginning of the <em>kbuf</em>
data section.</p></div>
<div class="paragraph"><p><strong>kbuf_read_buffer()</strong> returns the index of the end of the last event that was filled in
<em>buffer</em>. If there are no more events to copy from <em>start</em> then 0 is returned. If <em>len</em>
is not big enough to hold any events, then -1 is returned.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_example">EXAMPLE</h2>
<div class="sectionbody">
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #000080">#include</span></span> <span style="color: #FF0000">&lt;stdio.h&gt;</span>
<span style="font-weight: bold"><span style="color: #000080">#include</span></span> <span style="color: #FF0000">&lt;stdlib.h&gt;</span>
<span style="font-weight: bold"><span style="color: #000080">#include</span></span> <span style="color: #FF0000">&lt;fcntl.h&gt;</span>
<span style="font-weight: bold"><span style="color: #000080">#include</span></span> <span style="color: #FF0000">&lt;unistd.h&gt;</span>
<span style="font-weight: bold"><span style="color: #000080">#include</span></span> <span style="color: #FF0000">&lt;sys/stat.h&gt;</span>

<span style="font-weight: bold"><span style="color: #000080">#include</span></span> <span style="color: #FF0000">&lt;kbuffer.h&gt;</span>

<span style="color: #009900">int</span> <span style="font-weight: bold"><span style="color: #000000">main</span></span> <span style="color: #990000">(</span><span style="color: #009900">int</span> argc<span style="color: #990000">,</span> <span style="color: #009900">char</span> <span style="color: #990000">**</span>argv<span style="color: #990000">)</span>
<span style="color: #FF0000">{</span>
        <span style="color: #009900">unsigned</span> <span style="color: #009900">long</span> <span style="color: #009900">long</span> ts<span style="color: #990000">;</span>
        <span style="font-weight: bold"><span style="color: #0000FF">struct</span></span> <span style="color: #008080">kbuffer</span> <span style="color: #990000">*</span>kbuf<span style="color: #990000">;</span>
        <span style="font-weight: bold"><span style="color: #0000FF">struct</span></span> <span style="color: #008080">stat</span> st<span style="color: #990000">;</span>
        <span style="color: #009900">char</span> <span style="color: #990000">*</span>buf<span style="color: #990000">;</span>
        <span style="color: #009900">void</span> <span style="color: #990000">*</span>event<span style="color: #990000">;</span>
        <span style="color: #009900">int</span> save_offset <span style="color: #990000">=</span> <span style="color: #990000">-</span><span style="color: #993399">1</span><span style="color: #990000">;</span>
        <span style="color: #009900">int</span> record_size<span style="color: #990000">;</span>
        <span style="color: #009900">int</span> offset<span style="color: #990000">;</span>
        <span style="color: #009900">int</span> index<span style="color: #990000">;</span>
        <span style="color: #009900">int</span> size<span style="color: #990000">;</span>
        <span style="color: #009900">int</span> ret<span style="color: #990000">;</span>
        <span style="color: #009900">int</span> fd<span style="color: #990000">;</span>
        <span style="color: #009900">int</span> i <span style="color: #990000">=</span> <span style="color: #993399">0</span><span style="color: #990000">;</span>

        <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(</span>argc <span style="color: #990000">&lt;</span> <span style="color: #993399">2</span><span style="color: #990000">)</span> <span style="color: #FF0000">{</span>
                <span style="font-weight: bold"><span style="color: #000000">printf</span></span><span style="color: #990000">(</span><span style="color: #FF0000">"usage: %s raw-subbuffer-page</span><span style="color: #CC33CC">\n</span><span style="color: #FF0000">"</span><span style="color: #990000">,</span> argv<span style="color: #990000">[</span><span style="color: #993399">0</span><span style="color: #990000">]);</span>
                <span style="font-weight: bold"><span style="color: #000000">printf</span></span><span style="color: #990000">(</span><span style="color: #FF0000">" Try: dd count=1 bs=4096 if=/sys/kernel/tracing/per_cpu/cpu0/trace_pipe_raw of=/tmp/file</span><span style="color: #CC33CC">\n</span><span style="color: #FF0000">"</span><span style="color: #990000">);</span>
                <span style="font-weight: bold"><span style="color: #000000">exit</span></span><span style="color: #990000">(</span><span style="color: #993399">0</span><span style="color: #990000">);</span>
        <span style="color: #FF0000">}</span>

        <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #000000">stat</span></span><span style="color: #990000">(</span>argv<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">],</span> <span style="color: #990000">&amp;</span>st<span style="color: #990000">)</span> <span style="color: #990000">&lt;</span> <span style="color: #993399">0</span><span style="color: #990000">)</span> <span style="color: #FF0000">{</span>
                <span style="font-weight: bold"><span style="color: #000000">perror</span></span><span style="color: #990000">(</span><span style="color: #FF0000">"stat"</span><span style="color: #990000">);</span>
                <span style="font-weight: bold"><span style="color: #000000">exit</span></span><span style="color: #990000">(-</span><span style="color: #993399">1</span><span style="color: #990000">);</span>
        <span style="color: #FF0000">}</span>

        buf <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">malloc</span></span><span style="color: #990000">(</span>st<span style="color: #990000">.</span>st_size<span style="color: #990000">);</span>
        <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(!</span>buf<span style="color: #990000">)</span> <span style="color: #FF0000">{</span>
                <span style="font-weight: bold"><span style="color: #000000">perror</span></span><span style="color: #990000">(</span><span style="color: #FF0000">"Allocating buffer"</span><span style="color: #990000">);</span>
                <span style="font-weight: bold"><span style="color: #000000">exit</span></span><span style="color: #990000">(-</span><span style="color: #993399">1</span><span style="color: #990000">);</span>
        <span style="color: #FF0000">}</span>

        fd <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">open</span></span><span style="color: #990000">(</span>argv<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">],</span> O_RDONLY<span style="color: #990000">);</span>
        <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(</span>fd <span style="color: #990000">&lt;</span> <span style="color: #993399">0</span><span style="color: #990000">)</span> <span style="color: #FF0000">{</span>
                <span style="font-weight: bold"><span style="color: #000000">perror</span></span><span style="color: #990000">(</span>argv<span style="color: #990000">[</span><span style="color: #993399">1</span><span style="color: #990000">]);</span>
                <span style="font-weight: bold"><span style="color: #000000">exit</span></span><span style="color: #990000">(-</span><span style="color: #993399">1</span><span style="color: #990000">);</span>
        <span style="color: #FF0000">}</span>

        ret <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">read</span></span><span style="color: #990000">(</span>fd<span style="color: #990000">,</span> buf<span style="color: #990000">,</span> st<span style="color: #990000">.</span>st_size<span style="color: #990000">);</span>
        <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(</span>ret <span style="color: #990000">&lt;</span> <span style="color: #993399">0</span><span style="color: #990000">)</span> <span style="color: #FF0000">{</span>
                <span style="font-weight: bold"><span style="color: #000000">perror</span></span><span style="color: #990000">(</span><span style="color: #FF0000">"Reading buffer"</span><span style="color: #990000">);</span>
                <span style="font-weight: bold"><span style="color: #000000">exit</span></span><span style="color: #990000">(-</span><span style="color: #993399">1</span><span style="color: #990000">);</span>
        <span style="color: #FF0000">}</span>
        <span style="font-weight: bold"><span style="color: #000000">close</span></span><span style="color: #990000">(</span>fd<span style="color: #990000">);</span>

        kbuf <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">kbuffer_alloc</span></span><span style="color: #990000">(</span>KBUFFER_ENDIAN_SAME_AS_HOST<span style="color: #990000">,</span>
                             KBUFFER_LSIZE_SAME_AS_HOST<span style="color: #990000">);</span>
        <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(!</span>kbuf<span style="color: #990000">)</span> <span style="color: #FF0000">{</span>
                <span style="font-weight: bold"><span style="color: #000000">perror</span></span><span style="color: #990000">(</span><span style="color: #FF0000">"Creating kbuffer"</span><span style="color: #990000">);</span>
                <span style="font-weight: bold"><span style="color: #000000">exit</span></span><span style="color: #990000">(-</span><span style="color: #993399">1</span><span style="color: #990000">);</span>
        <span style="color: #FF0000">}</span>
        ret <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">kbuffer_load_subbuffer</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">,</span> buf<span style="color: #990000">);</span>
        <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(</span>ret <span style="color: #990000">&lt;</span> <span style="color: #993399">0</span><span style="color: #990000">)</span> <span style="color: #FF0000">{</span>
                <span style="font-weight: bold"><span style="color: #000000">perror</span></span><span style="color: #990000">(</span><span style="color: #FF0000">"Loading sub bufer"</span><span style="color: #990000">);</span>
                <span style="font-weight: bold"><span style="color: #000000">exit</span></span><span style="color: #990000">(-</span><span style="color: #993399">1</span><span style="color: #990000">);</span>
        <span style="color: #FF0000">}</span>

        <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(</span><span style="font-weight: bold"><span style="color: #000000">kbuffer_subbuffer_size</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">)</span> <span style="color: #990000">&gt;</span> st<span style="color: #990000">.</span>st_size<span style="color: #990000">)</span> <span style="color: #FF0000">{</span>
                <span style="font-weight: bold"><span style="color: #000000">fprintf</span></span><span style="color: #990000">(</span>stderr<span style="color: #990000">,</span> <span style="color: #FF0000">"kbuffer is bigger than raw size %d &gt; %ld</span><span style="color: #CC33CC">\n</span><span style="color: #FF0000">"</span><span style="color: #990000">,</span>
                        <span style="font-weight: bold"><span style="color: #000000">kbuffer_subbuffer_size</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">),</span> st<span style="color: #990000">.</span>st_size<span style="color: #990000">);</span>
                <span style="font-weight: bold"><span style="color: #000000">exit</span></span><span style="color: #990000">(-</span><span style="color: #993399">1</span><span style="color: #990000">);</span>
        <span style="color: #FF0000">}</span>

        ret <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">kbuffer_missed_events</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">);</span>
        <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(</span>ret<span style="color: #990000">)</span> <span style="color: #FF0000">{</span>
                <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(</span>ret <span style="color: #990000">&gt;</span> <span style="color: #993399">0</span><span style="color: #990000">)</span>
                        <span style="font-weight: bold"><span style="color: #000000">printf</span></span><span style="color: #990000">(</span><span style="color: #FF0000">"Missed %d events before this buffer</span><span style="color: #CC33CC">\n</span><span style="color: #FF0000">"</span><span style="color: #990000">,</span> ret<span style="color: #990000">);</span>
                <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>
                        <span style="font-weight: bold"><span style="color: #000000">printf</span></span><span style="color: #990000">(</span><span style="color: #FF0000">"Missed unknown number of events before this buffer</span><span style="color: #CC33CC">\n</span><span style="color: #FF0000">"</span><span style="color: #990000">);</span>
        <span style="color: #FF0000">}</span>
        <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #FF0000">{</span>
                event <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">kbuffer_read_event</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">,</span> <span style="color: #990000">&amp;</span>ts<span style="color: #990000">);</span>
                <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(</span>event<span style="color: #990000">)</span> <span style="color: #FF0000">{</span>
                        record_size <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">kbuffer_curr_size</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">);</span>
                        offset <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">kbuffer_curr_offset</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">);</span>
                        index <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">kbuffer_curr_index</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">);</span>
                        size <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">kbuffer_event_size</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">);</span>

                        <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(</span>i <span style="color: #990000">==</span> <span style="color: #993399">20</span><span style="color: #990000">)</span>
                                save_offset <span style="color: #990000">=</span> offset<span style="color: #990000">;</span>
                        <span style="font-weight: bold"><span style="color: #000000">printf</span></span><span style="color: #990000">(</span><span style="color: #FF0000">" event %3d ts:%lld</span><span style="color: #CC33CC">\t</span><span style="color: #FF0000">record_size:%d size:%d</span><span style="color: #CC33CC">\t</span><span style="color: #FF0000">index:%d offset:%d</span><span style="color: #CC33CC">\n</span><span style="color: #FF0000">"</span><span style="color: #990000">,</span>
                               i<span style="color: #990000">++,</span> ts<span style="color: #990000">,</span> record_size<span style="color: #990000">,</span> size<span style="color: #990000">,</span> index<span style="color: #990000">,</span> offset<span style="color: #990000">);</span>
                        event <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">kbuffer_next_event</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">,</span> NULL<span style="color: #990000">);</span>
                <span style="color: #FF0000">}</span>
        <span style="color: #FF0000">}</span> <span style="font-weight: bold"><span style="color: #0000FF">while</span></span> <span style="color: #990000">(</span>event<span style="color: #990000">);</span>

        <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(!</span>event<span style="color: #990000">)</span>
                <span style="font-weight: bold"><span style="color: #000000">printf</span></span><span style="color: #990000">(</span><span style="color: #FF0000">"Finished sub buffer</span><span style="color: #CC33CC">\n</span><span style="color: #FF0000">"</span><span style="color: #990000">);</span>

        <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(</span>save_offset <span style="color: #990000">&gt;</span> <span style="color: #993399">0</span><span style="color: #990000">)</span> <span style="color: #FF0000">{</span>
                event <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">kbuffer_read_at_offset</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">,</span> save_offset<span style="color: #990000">,</span> <span style="color: #990000">&amp;</span>ts<span style="color: #990000">);</span>
                <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">(!</span>event<span style="color: #990000">)</span> <span style="color: #FF0000">{</span>
                        <span style="font-weight: bold"><span style="color: #000000">fprintf</span></span><span style="color: #990000">(</span>stderr<span style="color: #990000">,</span> <span style="color: #FF0000">"Funny, can't find event 20 at offset %d</span><span style="color: #CC33CC">\n</span><span style="color: #FF0000">"</span><span style="color: #990000">,</span> save_offset<span style="color: #990000">);</span>
                        <span style="font-weight: bold"><span style="color: #000000">exit</span></span><span style="color: #990000">(-</span><span style="color: #993399">1</span><span style="color: #990000">);</span>
                <span style="color: #FF0000">}</span>
                record_size <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">kbuffer_curr_size</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">);</span>
                offset <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">kbuffer_curr_offset</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">);</span>
                index <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">kbuffer_curr_index</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">);</span>
                size <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">kbuffer_event_size</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">);</span>

                <span style="font-weight: bold"><span style="color: #000000">printf</span></span><span style="color: #990000">(</span><span style="color: #FF0000">"</span><span style="color: #CC33CC">\n</span><span style="color: #FF0000"> saved event 20 ts:%lld</span><span style="color: #CC33CC">\t</span><span style="color: #FF0000">record_size:%d size:%d</span><span style="color: #CC33CC">\t</span><span style="color: #FF0000">index:%d offset:%d</span><span style="color: #CC33CC">\n\n</span><span style="color: #FF0000">"</span><span style="color: #990000">,</span>
                       ts<span style="color: #990000">,</span> record_size<span style="color: #990000">,</span> size<span style="color: #990000">,</span> index<span style="color: #990000">,</span> offset<span style="color: #990000">);</span>
        <span style="color: #FF0000">}</span>
        <span style="font-weight: bold"><span style="color: #000000">kbuffer_free</span></span><span style="color: #990000">(</span>kbuf<span style="color: #990000">);</span>

        <span style="font-weight: bold"><span style="color: #0000FF">return</span></span> <span style="color: #993399">0</span><span style="color: #990000">;</span>
<span style="color: #FF0000">}</span></tt></pre></div></div>
</div>
</div>
<div class="sect1">
<h2 id="_files">FILES</h2>
<div class="sectionbody">
<div class="verseblock">
<pre class="content"><strong>event-parse.h</strong>
        Header file to include in order to have access to the library APIs.
<strong>-ltraceevent</strong>
        Linker switch to add when building a program that uses the library.</pre>
<div class="attribution">
</div></div>
</div>
</div>
<div class="sect1">
<h2 id="_see_also">SEE ALSO</h2>
<div class="sectionbody">
<div class="paragraph"><p><strong>libtraceevent</strong>(3), <strong>trace-cmd</strong>(1)</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_author">AUTHOR</h2>
<div class="sectionbody">
<div class="verseblock">
<pre class="content"><strong>Steven Rostedt</strong> &lt;<a href="mailto:rostedt@goodmis.org">rostedt@goodmis.org</a>&gt;, author of <strong>libtraceevent</strong>.</pre>
<div class="attribution">
</div></div>
</div>
</div>
<div class="sect1">
<h2 id="_reporting_bugs">REPORTING BUGS</h2>
<div class="sectionbody">
<div class="paragraph"><p>Report bugs to  &lt;<a href="mailto:linux-trace-devel@vger.kernel.org">linux-trace-devel@vger.kernel.org</a>&gt;</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_license">LICENSE</h2>
<div class="sectionbody">
<div class="paragraph"><p>libtraceevent is Free Software licensed under the GNU LGPL 2.1</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_resources">RESOURCES</h2>
<div class="sectionbody">
<div class="paragraph"><p><a href="https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/">https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/</a></p></div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
Last updated
 2024-10-11 21:26:45 UTC
</div>
</div>
</body>
</html>
Name	Size	Permission
libtraceevent-commands.html	29719 bytes	0644
libtraceevent-cpus.html	21389 bytes	0644
libtraceevent-debug.html	23700 bytes	0644
libtraceevent-endian_read.html	21789 bytes	0644
libtraceevent-event_find.html	24754 bytes	0644
libtraceevent-event_get.html	23957 bytes	0644
libtraceevent-event_list.html	25272 bytes	0644
libtraceevent-event_print.html	25548 bytes	0644
libtraceevent-field_find.html	27447 bytes	0644
libtraceevent-field_get_val.html	28250 bytes	0644
libtraceevent-field_print.html	28610 bytes	0644
libtraceevent-field_read.html	23026 bytes	0644
libtraceevent-fields.html	25398 bytes	0644
libtraceevent-file_endian.html	22166 bytes	0644
libtraceevent-filter.html	35978 bytes	0644
libtraceevent-func_apis.html	31736 bytes	0644
libtraceevent-func_find.html	29117 bytes	0644
libtraceevent-handle.html	23854 bytes	0644
libtraceevent-header_page.html	23961 bytes	0644
libtraceevent-host_endian.html	23585 bytes	0644
libtraceevent-kbuffer-create.html	39660 bytes	0644
libtraceevent-kbuffer-read.html	47477 bytes	0644
libtraceevent-kbuffer-timestamp.html	42976 bytes	0644
libtraceevent-kvm-plugin.html	48364 bytes	0644
libtraceevent-log.html	21347 bytes	0644
libtraceevent-long_size.html	21356 bytes	0644
libtraceevent-page_size.html	23185 bytes	0644
libtraceevent-parse-files.html	31025 bytes	0644
libtraceevent-parse_event.html	23696 bytes	0644
libtraceevent-parse_head.html	22352 bytes	0644
libtraceevent-plugins.html	28186 bytes	0644
libtraceevent-record_parse.html	26291 bytes	0644
libtraceevent-reg_event_handler.html	32678 bytes	0644
libtraceevent-reg_print_func.html	30685 bytes	0644
libtraceevent-set_flag.html	23538 bytes	0644
libtraceevent-strerror.html	22495 bytes	0644
libtraceevent-tseq.html	30737 bytes	0644
libtraceevent.html	37316 bytes	0644
File Content: libtraceevent-kbuffer-read.html

File Content: `libtraceevent-kbuffer-read.html`
