'\" t
.\" Title: libtracefs
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 01/13/2024
.\" Manual: libtracefs Manual
.\" Source: libtracefs 1.8.0
.\" Language: English
.\"
.TH "LIBTRACEFS" "3" "01/13/2024" "libtracefs 1\&.8\&.0" "libtracefs Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
tracefs_find_cid_pid, tracefs_instance_find_cid_pid, tracefs_time_conversion \- helper functions to handle tracing guests
.SH "SYNOPSIS"
.sp
.nf
\fB#include \fR
char *\fBtracefs_find_cid_pid\fR(int \fIcid\fR);
char *\fBtracefs_instance_find_cid_pid\fR(struct tracefs_instance *\fIinstance\fR, int \fIcid\fR);
int \fBtracefs_time_conversion\fR(int \fIcpu\fR, int *\fIshift\fR, int *\fImulti\fR, long long *offset);
.fi
.SH "DESCRIPTION"
.sp
The \fBtracefs_find_cid_pid\fR() will use tracing to follow the wakeups of connecting to the given \fIcid\fR in order to find the pid of the guest thread that belongs to the vsocket cid\&. It will then read the proc file system to find the thread leader, and it will return the pid of the thread leader\&.
.sp
The \fBtracefs_instance_find_cid_pid\fR() is the same as \fBtracefs_find_cid_pid\fR() but defines the instance to use to perform the tracing in\&. If NULL it will use the top level buffer to perform the tracing\&.
.sp
The \fBtracefs_time_conversion\fR() will return the values used by the kernel to convert the raw time stamp counter into nanoseconds for the given \fIcpu\fR\&. Pointers for \fIshift\fR, \fImulti\fR and \fIoffset\fR can be NULL to be ignored, otherwise they are set with the shift, multiplier and offset repectively\&.
.SH "RETURN VALUE"
.sp
Both \fBtracefs_find_cid_pid\fR() and \fBtracefs_instance_find_cid_pid\fR() will return the pid of the guest main thread that belongs to the \fIcid\fR, or \-1 on error (or not found)\&.
.SH "EXAMPLE"
.sp
.if n \{\
.RS 4
.\}
.nf
#include
#include
#include
#define MAX_CID 256
static void find_cid(struct tracefs_instance *instance, int cid)
{
int pid;
pid = tracefs_instance_find_cid_pid(instance, cid);
if (pid >= 0)
printf("%d\et%d\en", cid, pid);
}
static int find_cids(void)
{
struct tracefs_instance *instance;
char *name;
int cid;
int ret;
ret = asprintf(&name, "vsock_find\-%d\en", getpid());
if (ret < 0)
return ret;
instance = tracefs_instance_create(name);
free(name);
if (!instance)
return \-1;
for (cid = 0; cid < MAX_CID; cid++)
find_cid(instance, cid);
tracefs_event_disable(instance, NULL, NULL);
tracefs_instance_destroy(instance);
tracefs_instance_free(instance);
return 0;
}
struct time_info {
int shift;
int multi;
};
static void show_time_conversion(void)
{
struct time_info *tinfo;
int cpus;
int cpu;
int ret;
cpus = sysconf(_SC_NPROCESSORS_CONF);
tinfo = calloc(cpus, sizeof(*tinfo));
if (!tinfo)
exit(\-1);
for (cpu = 0; cpu < cpus; cpu++) {
ret = tracefs_time_conversion(cpu,
&tinfo[cpu]\&.shift,
&tinfo[cpu]\&.multi,
NULL);
if (ret)
break;
}
if (cpu != cpus) {
if (!cpu) {
perror("tracefs_time_conversion");
exit(\-1);
}
printf("Only read %d of %d CPUs", cpu, cpus);
cpus = cpu + 1;
}
/* Check if all the shift and mult values are the same */
for (cpu = 1; cpu < cpus; cpu++) {
if (tinfo[cpu \- 1]\&.shift != tinfo[cpu]\&.shift)
break;
if (tinfo[cpu \- 1]\&.multi != tinfo[cpu]\&.multi)
break;
}
if (cpu == cpus) {
printf("All cpus have:\en");
printf(" shift: %d\en", tinfo[0]\&.shift);
printf(" multi: %d\en", tinfo[0]\&.multi);
printf("\en");
return;
}
for (cpu = 0; cpu < cpus; cpu++) {
printf("CPU: %d\en", cpu);
printf(" shift: %d\en", tinfo[cpu]\&.shift);
printf(" multi: %d\en", tinfo[cpu]\&.multi);
printf("\en");
}
}
int main(int argc, char *argv[])
{
show_time_conversion();
find_cids();
exit(0);
}
.fi
.if n \{\
.RE
.\}
.SH "FILES"
.sp
.if n \{\
.RS 4
.\}
.nf
\fBtracefs\&.h\fR
Header file to include in order to have access to the library APIs\&.
\fB\-ltracefs\fR
Linker switch to add when building a program that uses the library\&.
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBlibtracefs\fR(3), \fBlibtraceevent\fR(3), \fBtrace\-cmd\fR(1)
.SH "AUTHOR"
.sp
.if n \{\
.RS 4
.\}
.nf
\fBSteven Rostedt\fR <\m[blue]\fBrostedt@goodmis\&.org\fR\m[]\&\s-2\u[1]\d\s+2>
\fBTzvetomir Stoyanov\fR <\m[blue]\fBtz\&.stoyanov@gmail\&.com\fR\m[]\&\s-2\u[2]\d\s+2>
.fi
.if n \{\
.RE
.\}
.SH "REPORTING BUGS"
.sp
Report bugs to <\m[blue]\fBlinux\-trace\-devel@vger\&.kernel\&.org\fR\m[]\&\s-2\u[3]\d\s+2>
.SH "LICENSE"
.sp
libtracefs is Free Software licensed under the GNU LGPL 2\&.1
.SH "RESOURCES"
.sp
\m[blue]\fBhttps://git\&.kernel\&.org/pub/scm/libs/libtrace/libtracefs\&.git/\fR\m[]
.SH "COPYING"
.sp
Copyright (C) 2020 VMware, Inc\&. Free use of this software is granted under the terms of the GNU Public License (GPL)\&.
.SH "NOTES"
.IP " 1." 4
rostedt@goodmis.org
.RS 4
\%mailto:rostedt@goodmis.org
.RE
.IP " 2." 4
tz.stoyanov@gmail.com
.RS 4
\%mailto:tz.stoyanov@gmail.com
.RE
.IP " 3." 4
linux-trace-devel@vger.kernel.org
.RS 4
\%mailto:linux-trace-devel@vger.kernel.org
.RE