xpagetfd(3)

💖 XPAGetFd — bestie's guide to the xpagetfd(3) manual page 💖

ok so we're deep in the xpagetfd(3) page from the XPA gang (SAORD Documentation era, we love her) and she's about pulling data off one or more XPA servers and yeeting it straight into files. let's go 🦋

---

✨ NAME ✨

XPAGetFd — retrieve data from one or more XPA servers and write to files 💅

---

🌸 SYNOPSIS 🌸

#include <xpa.h>

int XPAGetFd(XPA xpa,
             char *template, char *paramlist, char *mode,
             int *fds, char **names, char **messages, int n);

---

🎀 DESCRIPTION 🎀

ok so the whole vibe: you're grabbing data from one or more XPA servers whose class:name identifier matches the template you gave, and writing it to files that are hooked up to one or more standard I/O fds — and by fds we mean the handles you get back from open(). 🫶

A template shaped like "class1:name1" gets sent to the XPA name server, and it comes back with a list of at most ABS(n) matching XPA servers. Then a connection is established with every one of those servers, and the paramlist string gets passed along to the server as the data transfer request kicks off. If you pass an XPA struct into the call, the persistent connections get updated like described above. If you don't, temporary connections are made to the servers instead — and those get closed when the call completes. bye bestie 👋

Then XPAGetFd() does its thing: it retrieves the data from the XPA servers and writes it out to the fds — the ones associated with one or more fds, i.e. the results from open. Here's the tea on n:

• if n is positive, there will be n fds and each server's data gets sent to its own separate fd 💖
• if n is negative, there's only 1 fd and all the data gets sent to that single fd (and yes, that's literally how xpaget is implemented, no cap)

A string holding the class:name and ip:port gets stored in the name array. And if a given server returned an error, or the server callback sends a message back to the client, that message gets stored in the matching element of the messages array. NB: if you specify them, the name and messages arrays must be of size n or greater. don't play yourself 🙈

The returned message string will look like one of these:

XPA$ERROR   error-message (class:name ip:port)

or

XPA$MESSAGE message     (class:name ip:port)

heads up bestie: when there's an error stored in a messages entry, the corresponding bufs and lens entry may or may not be NULL and 0 (respectively) — it totally depends on the particularities of the server. so don't assume, ok? 💀

The return value holds the actual number of servers that were processed. so that value is literally the number of valid entries in the bufs, lens, names, and messages arrays, and you can use it to loop through them. If names and/or messages is NULL, no information gets passed back in that array. periodt. ✨

---

🌈 the mode string 🌈

The mode string is shaped like: "key1=value1,key2=value2,..." and here's the one keyword it recognizes:

• ack — value: true/false, default: true. if false, don't wait for ack from server (after callback completes)

ngl the ack keyword is not very useful, since the server completes the callback in order to return the data anyway. It's here for completion (and perhaps for future usefulness). iconic of her honestly 💅

---

🍓 Example 🍓

#include <xpa.h>
#define NXPA 10
int  i, got;
int fds[NXPA];
char *names[NXPA];
char *messages[NXPA];
for(i=0; i<NXPA; i++)
  fds[i] = open(...);
got = XPAGetFd(NULL, "ds9", "file", NULL, fds, names, messages, NXPA);
for(i=0; i<got; i++){
  if( messages[i] != NULL ){
    /* error processing */
    fprintf(stderr, "ERROR: %s (%s)\n", messages[i], names[i]);
  }
  if( names[i] )
    free(names[i]);
  if( messages[i] )
    free(messages[i]);
}

---

👑 SEE ALSO 👑

See xpa(n) for a list of XPA help pages ⭐

---

and that's the whole page bestie, you ate it 💖 this was version 2.1.15, dated July 23, 2013 — so yes, she's a little vintage but she's still serving, and honestly? she's giving main character energy. mwah 🎀✨