PMTIME(3)

💖 PMTIME(3) 💖

okay bestie, gather round, because this is the time control saga from the Library Functions Manual and it's honestly giving main character energy ✨

---

🎀 NAME 🎀

pmTimeConnect, pmTimeDisconnect, pmTimeRecv, pmTimeSendAck, pmTimeShowDialog — the time control functions that keep the archive position AND the update interval in sync between one or more applications 🫶

---

🌸 C SYNOPSIS 🌸

#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 💅

so these functions are part of the Performance Metrics Applications Programming Interface (PMAPI), and their whole vibe is giving everyone a uniform mechanism so apps can replay archive data and report live data in a time synchronized way. iconic, honestly.

the pmTime structure has these fields, no cap:

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, your app should call pmTimeConnect to connect to the time control server, pmtime(1), and then just keep calling pmTimeRecv in the main loop of the application. lowkey that's it. on success, pmTimeConnect returns a non-negative file descriptor 💛. and if your app has multiple threads of control, instead of just blocking forever in pmTimeRecv, you can hand that file descriptor to select(2). in graphical apps? that fd can interface with the event loop. slay.

the port parameter to pmTimeConnect is the port number of the socket where the time control server is (or will be) listening for new connections. 📡

the state parameter to pmTimeConnect is used to initialize a brand new time control server OR to pass extra info to one that already exists. the start and finish fields indicate the chronological bounds that are interesting to the application. the showgui field says whether the time control server should initially show or hide the dialog. and the position, delta, and data fields indicate the initial archive position, the update interval, the time zone string, and the time zone label string. 🕰️

pmTimeRecv blocks until the time control server sends a command message. then it updates the state parameter and returns one of the PM_TCTL_* command identifiers. periodt.

---

✨ the commands, one by one ✨

• PM_TCTL_SET — tells the app it should seek to the archive position (peep pmSetMode(3)) that came back in the position field of the state parameter.
• PM_TCTL_STEP — tells the app to do an update, like advance (or rewind, if delta is negative) to the time indicated by position and then fetch new metric values, update the display, whatever. and here's the important bit bestie: so that several applications stay synchronized, the time control server will wait until all applications have acknowledged that they finished the step command. apps should call pmTimeSendAck once the step command has been processed. also note: PM_TCTL_STEP is the only command that requires an explicit acknowledgement. don't forget it or everyone's just... waiting. 😭
• PM_TCTL_VCRMODE — used by the time control server to indicate the current VCR mode. the value comes back in the mode field of the state parameter passed to pmTimeRecv, and it stays valid until the next PM_TCTL_VCRMODE command arrives.
• PM_TCTL_TZ — tells the app it should use a new timezone, as indicated in the newzone field of the state parameter.
• PM_TCTL_BOUNDS — sent to all applications whenever the time control server changes its chronological bounds. this can happen when a new application connects to the time control server, or when the user changes the bounds by hand. most applications will just ignore this one, ngl. 🙈
• PM_TCTL_GUIHIDE or PM_TCTL_GUISHOW — sent to all applications when the visibility of the time control server changes. this lets apps alter the text in menus or buttons to reflect the change. apps can change the visibility of the time control dialog themselves using the pmTimeShowDialog function. and the initial visibility? that's determined when the time control dialog is first created, by an application calling pmTimeConnect with the showgui field in the state parameter set to whatever value it wants. 💅

---

🦋 disconnecting 🦋

the pmTimeDisconnect function may be used to close the command socket to the time control server. super useful when apps need to change the connection mode, e.g. to divorce the current time control server and connect to a new one. it's giving ✨moving on✨.

ok but fr fr — keep your fields straight, because start, finish, showgui, newzone, position, delta, data and mode are all doing different jobs and the server is not gonna read your mind. 💀

---

🌈 SEE ALSO 🌈

pmtime(1), PMAPI(3) and pmSetMode(3). go read them, iykyk 🫶

---

this whole page is brought to you by Performance Co-Pilot, courtesy of Aconex, and it's dated PMTIME(3) — mwah, that's the sign-off bestie, stay synchronized 💖✨🎀