|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | C SYNOPSIS | DESCRIPTION | SEE ALSO | COLOPHON |
|
|
|
PMTIME(3) Library Functions Manual PMTIME(3)
pmTimeConnect, pmTimeDisconnect, pmTimeRecv, pmTimeSendAck,
pmTimeShowDialog - time control functions for synchronizing the
archive position and update interval between one or more
applications
#include <pcp/pmtime.h>
int pmTimeConnect(int port, pmTime *state);
int pmTimeDisconnect(int fd);
int pmTimeSendAck(int fd, struct timeval *fetchTime);
int pmTimeShowDialog(int fd, int show);
int pmTimeRecv(int fd, pmTime *state);
cc ... -lpcp_gui
These functions form part of the Performance Metrics Applications
Programming Interface (PMAPI) and are intended to provide a uni‐
form mechanism for applications to both replay archive data and
report live data in a time synchronized manner.
The pmTime structure has the following fields:
typedef struct {
unsigned int magic;
unsigned int length;
pm_tctl_command command;
pm_tctl_source source;
pm_tctl_state state;
pm_tctl_mode mode;
struct timeval delta;
struct timeval position;
struct timeval start; /* archive only */
struct timeval end; /* archive only */
char data[0]; /* arbitrary length info (TZ) */
} pmTime;
In the simplest case, the application should call pmTimeConnect to
connect to the time control server, pmtime(1), and then repeatedly
call pmTimeRecv in the main loop of the application. On success,
pmTimeConnect returns a non-negative file descriptor. In applica‐
tions which have multiple threads of control, rather than simply
blocking in pmTimeRecv, the file descriptor may be used in calls
to select(2). In graphical applications, the file descriptor may
be used to interface with the event loop.
The port parameter to pmTimeConnect is the port number of the
socket on which the time control server is (or will be) listening
for new connections.
The state parameter to pmTimeConnect is used to initialize a new
time control server or to pass additional information to an exist‐
ing time control server. The start and finish fields indicate the
chronological bounds interesting to the application. The showgui
field indicates whether the time control server should initially
show or hide the dialog. The position, delta, and data fields in‐
dicate the initial archive position, update interval, time zone
string and time zone label string.
pmTimeRecv blocks until the time control server sends a command
message. It then updates the state parameter and returns one of
the PM_TCTL_* command identifiers.
The PM_TCTL_SET command indicates the application should seek to
the archive position (see pmSetMode(3)) returned in the position
field of the state parameter.
The PM_TCTL_STEP command indicates the application should perform
an update, i.e. advance (or rewind, if delta is negative) to the
time indicated by position and then fetch new metric values, up‐
date the display or whatever. In order for several application to
remain synchronized, the time control server will wait until all
applications have acknowledged that they have completed the step
command. Applications should call pmTimeSendAck when the step
command has been processed. Note that PM_TCTL_STEP is the only
command that requires an explicit acknowledgement.
The PM_TCTL_VCRMODE command is used by the time control server to
indicate the current VCR mode.
The value is returned in the mode field of the state parameter
passed to pmTimeRecv, and remains valid until the next
PM_TCTL_VCRMODE command is received.
The PM_TCTL_TZ command indicates the application should use a new
time- zone, as indicated in the newzone field of the state parame‐
ter.
The PM_TCTL_BOUNDS command is sent to all applications when the
time control server changes its chronological bounds. This may
occur when a new application connects to the time control server
or the user changes the bounds manually. Most applications will
ignore this command.
The PM_TCTL_GUIHIDE or PM_TCTL_GUISHOW commands will be sent to
all applications when the visibility of the time control server
changes. This allows applications to alter the text in menus or
buttons to reflect this change. Applications may change the visi‐
bility of the time control dialog using the pmTimeShowDialog func‐
tion. The initial visibility is determined when the time control
dialog is first created by an application calling pmTimeConnect
with the showgui field in the state parameter set to the desired
value.
The pmTimeDisconnect function may be used to close the command
socket to the time control server. This is useful when applica‐
tions need to change the connection mode, e.g. to divorce the cur‐
rent time control server and connect to a new one.
pmtime(1), PMAPI(3) and pmSetMode(3).
This page is part of the PCP (Performance Co-Pilot) project. In‐
formation about the project can be found at ⟨http://www.pcp.io/⟩.
If you have a bug report for this manual page, send it to
pcp@groups.io. This page was obtained from the project's upstream
Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
2025-08-11. (At that time, the date of the most recent commit
that was found in the repository was 2025-08-11.) If you discover
any rendering problems in this HTML version of the page, or you
believe there is a better or more up-to-date source for the page,
or you have corrections or improvements to the information in this
COLOPHON (which is not part of the original manual page), send a
mail to man-pages@man7.org
Performance Co-Pilot Aconex PMTIME(3)
Pages that refer to this page: pcpintro(3)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|