LIBGVPR(3)

💖 LIBGVPR(3) 💖

okay bestie, gather round, because this is the library for graph filtering from the Library Functions Manual, and it's lowkey iconic. it's libgvpr, and it's about to make your app do graph stuff like it's nothing. no cap. 🦋

---

✨ NAME ✨

libgvpr — literally the library for graph filtering. that's it, that's the vibe. 🎀

---

🌸 SYNOPSIS 🌸

#include <graphviz/gvpr.h>

  /* If set, gvpr calls exit() on errors */
#define GV_USE_EXIT 1
  /* If set, gvpr stores output graphs in gvpropts */
#define GV_USE_OUTGRAPH 2

typedef ssize_t (*gvprwr) (void*, const char *buf, size_t nbyte, void*);

typedef struct {
    Agraph_t** ingraphs;      /* NULL-terminated array of input graphs */
    int n_outgraphs;          /* if GV_USE_OUTGRAPH set, output graphs */
    Agraph_t** outgraphs;
    gvprwr out;               /* write function for stdout */
    gvprwr err;               /* write function for stderr */
    int flags;
} gvpropts;

extern int gvpr (int argc, char *argv[], gvpropts* opts);

like, look at that struct. gvpropts is the whole personality. 👑

---

💅 DESCRIPTION 💅

so the gvpr library lets your application do general-purpose graph manipulation and filtering based on an awk-like language. (and if you want the full tea on that language, bestie, go read gvpr(1). it's all there. iykyk.) 📖

the library has exactly one entry point: the gvpr() function. main character energy, honestly. it gives you a standard argc/argv interface, plus a structure so you can pass in in-core graphs, your own application print functions, and a few extra options. 🫶

when you call it, gvpr() does this whole routine:

• it processes any flags you handed it in the argv array
• it compiles the gvpr program it's gonna run — that program comes either from the -f flag or from an item inside argv
• then it runs that program on every single input graph

now, about where those input graphs come from 👀 — if opts->ingraphs is non-NULL, that's taken as a NULL-terminated array of in-core graphs to use as input. otherwise, the unprocessed elements of argv get treated as the names of files containing graphs to be processed. and if, like, none remain? gvpr will just read from stdin. shy king behavior. 🙈

normally gvpr writes any output graph to stdout. but — plot twist — if the flag GV_USE_OUTGRAPH is set in opts->flags, the output graphs get stored in an array pointed to by opts->outgraphs, and the count lands in opts->n_outgraphs. in that case you, the application, must call agclose() on each output graph when you're done with it. don't forget, bestie, that's a real one. 🚨

and you can override the default write functions for stdout and stderr using the out and err fields in opts. when gvpr calls them, the second argument points to a buffer of characters to be written, and the third argument tells you how many characters there are. your function should return the number of bytes it actually wrote. slay. ✍️

---

🔥 RETURN VALUES 🔥

normally, gvpr returns 0 on success and non-zero if an error happens. any relevant error message will have been written to stderr, or your opts->err function will have been called. either way, you'll know. 💀

however — and this is the dramatic part — if GV_USE_EXIT is set in opts->flags, gvpr will call exit(3) in case of an error. like, it's out. it's leaving. no returns. periodt.

---

🌈 SEE ALSO 🌈

• gvpr(1)
• awk(1)
• cgraph(3)

go read them, they're all besties with this one. 🧚

---

👑 AUTHORS 👑

Emden Gansner (erg@research.att.com). an absolute legend, fr fr. 💜

---

and that's the whole page, gorgeous. this one's from the Library Functions Manual, dated 15 OCTOBER 2013, and it's filed under LIBGVPR(3). thanks for coming to my ted talk, mwah. 💖✨🎀🦋🌸