RMTSTATUS(3L)

💖 RMTSTATUS(3L) 💖

okay so bestie, you know how the manual name is Schily´s LIBRARY FUNCTIONS? yeah, that's the vibe. we're in librmt territory and it's giving remote tape server energy, no cap.

---

✨ NAME ✨

rmtstatus, rmtxstatus, _mtg2rmtg, _rmtg2mtg — these iconic functions literally request MTIOCGET on a connection to a remote tape server (the -lrmt situation, iykyk).

---

🎀 SYNOPSIS 🎀

#include <schily/librmt.h>
#include <schily/rmtio.h>

int rmtstatus(int remfd, struct mtget *mtp);

int rmtxstatus(int remfd, struct rmtget *mtp);

void _rmtg2mtg(struct mtget *mtp, struct rmtget *rmtp);

int _mtg2rmtg(struct rmtget *rmtp, struct mtget *mtp);

---

🦋 DESCRIPTION 🦋

💅 rmtstatus() and rmtxstatus()

okay so these two are the main characters here. they perform a MTIOCGET request to the remote server, and remfd is a file descriptor you previously got from calling rmtgetconn(3) — like, you can't just roll up with any fd, bestie, you gotta have that connection first.

so struct mtget is the local magnetic tape status structure, and struct rmtget is the enhanced magnetic tape status structure from librmt. very demure, very mindful.

now listen — rmtstatus(3) and rmtxstatus(3) will fail if there was no previous successful rmtopen(3) before. like, you can't skip steps, periodt. 💀

both of them take care of using RMT protocol VERSION 1 if the remote side implements support for protocol version 1. slay.

but here's the tea: rmtstatus(3) is outdated and should be avoided because the results in struct mtget will be the least common denominator of the local and remote variants of the structure. it's giving compromise energy, not icon energy. use rmtxstatus(3) instead, fr fr.

the member mt_xflags in struct rmtget contains a bitmap that indicates which members of the structure contain valid values. see mtio(4) for more information, bestie. 🫶

🌸 _rmtg2mtg()

converts a struct rmtget into a struct mtget. simple as that. conversion queen. ✨

🌈 _mtg2rmtg()

converts a struct mtget into a struct rmtget and sets the member mt_xflags in struct rmtget to contain a bitmap that indicates which members of struct mtget are present in the local implementation. multitasking legend. 👑

---

⭐ RETURN VALUES ⭐

💜 rmtstatus() and rmtxstatus()

return a value >= 0 if the remote ioctl(f, MTIOCGET, struct mtget *) succeeds. that's the good ending, bestie. 🌸

---

🔥 ERRORS 🔥

rmtstatus() and rmtxstatus() return -1 on error and set errno to the errno value retrieved from the remote server. it's giving long-distance error propagation, ngl.

💀 _mtg2rmtg()

returns -1 if no value from the local struct mtget could be converted to the abstract struct rmtget. like, nothing made it through. rough.

---

🧚 EXAMPLES 🧚

okay so here's the whole flow in action, bestie — this is literally the blueprint:

int  remfd;
char *remfn;
char host[256];
int  iosize = 10240;     /* socket send/receive size to set up */
struct rmtget rmtg;

if ((remfn = rmtfilename(filename)) != NULL) {
     rmthostname(host, sizeof (host), filename);

     if ((remfd = rmtgetconn(host, iosize, 0)) < 0)
          comerrno(EX_BAD, "Cannot get connection to '%s'.\n",
               /* errno not valid !! */      host);
}

if (rmtopen(remfd, remfn, mode) < 0)
     comerr("Cannot open '%s'.\n", remfn);

if (rmtxstatus(remfd, &rmtg) < 0)
     comerr("Cannot retrieve magnetic tape status from '%s'.\n", remfn);

rmtclose(remfd);

like, get the filename, get the hostname, get the connection, open it, grab the status with rmtxstatus, then rmtclose and you're done. iconic workflow. 🎀

---

👑 SEE ALSO 👑

rmt(1), rsh(1), ssh(1), rcmd(3), rmtinit(3), rmtdebug(3), rmtrmt(3), rmtrsh(3), rmthostname(3), rmtfilename(3), rmtgetconn(3), rmtopen(3), rmtioctl(3), rmtclose(3), rmtread(3), rmtwrite(3), rmtseek(3), rmtxstatus(3), rmtstatus(3), _mtg2rmtg(3), _rmtg2mtg(3), errmsgno(3), mtio(4)

the whole friend group, honestly. 🫶

---

🙈 BUGS 🙈

if local and remote errno values do not match, programs may get confused. like, the error codes are speaking different languages and nobody's translating. 😭

mail other bugs and suggestions to schilytools@mlists.in-berlin.de or open a ticket at https://codeberg.org/schilytools/schilytools/issues.

the mailing list archive may be found at:

https://mlists.in-berlin.de/mailman/listinfo/schilytools-mlists.in-berlin.de.

---

💖 AUTHORS 💖

librmt has been written in 1990 by Joerg Schilling. in 1995, support for RMT VERSION 1 has been added. librmt is now maintained by the schilytools project authors. legacy icon behavior. ✨

---

🍓 SOURCE DOWNLOAD 🍓

the source code for librmt is included in the schilytools project and may be retrieved from the schilytools project at Codeberg at

https://codeberg.org/schilytools/schilytools.

the download directory is

https://codeberg.org/schilytools/schilytools/releases.

---

so yeah bestie, that's the whole page — Joerg Schilling wrote it, the version date is 2022/10/06, and it's the RMTSTATUS(3L) page from Schily´s LIBRARY FUNCTIONS. go off and request those MTIOCGETs responsibly 💅✨