pmtime(3) — Linux manual page


PMTIME(3)               Library Functions Manual               PMTIME(3)

NAME         top

       pmTimeConnect, pmTimeDisconnect, pmTimeRecv, pmTimeSendAck,
       pmTimeShowDialog - time control functions for synchronizing the
       archive position and update interval between one or more

C SYNOPSIS         top

       #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

DESCRIPTION         top

       These functions form part of the Performance Metrics Applications
       Programming Interface (PMAPI) and are intended to provide a
       uniform 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 applications 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
       existing 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 indicate 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,
       update 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

       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
       visibility of the time control dialog using the pmTimeShowDialog
       function.  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
       applications need to change the connection mode, e.g. to divorce
       the current time control server and connect to a new one.

SEE ALSO         top

       pmtime(1), PMAPI(3) and pmSetMode(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨⟩.  If you have a bug report for this manual
       page, send it to  This page was obtained from the
       project's upstream Git repository
       ⟨⟩ on 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  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

Performance Co-Pilot             Aconex                        PMTIME(3)

Pages that refer to this page: pcpintro(3)