realmmgr(3)

📦
version 2.2.3 · 3 versions
, in arch rolling

🎀 realmmgr(3) — Net::DNS::SEC::Tools::realmmgr 🎀

okay so bestie, this is a page from the User Contributed Perl Documentation and honestly? it's a whole vibe. it's giving "let me talk to the realms manager" energy and we're gonna get through it together 💅

✨ NAME ✨

Net::DNS::SEC::Tools::realmmgr — the module that lets your program talk to the DNSSEC-Tools dtrealms realms manager. like a little walkie-talkie but for realms 🫶

✨ SYNOPSIS ✨

  use Net::DNS::SEC::Tools::realmmgr;

  $dir = realmmgr_dir();

  $idfile = realmmgr_idfile();

  $id = realmmgr_getid();

  realmmgr_dropid();

  realmmgr_rmid();

  realmmgr_cmdint();

  $runflag = realmmgr_running();

  realmmgr_halt();

  realmmgr_channel(1);
  ($cmd,$data) = realmmgr_getcmd();
  $ret = realmmgr_verifycmd($cmd);

  realmmgr_sendcmd(CHANNEL_CLOSE,REALMCMD_STARTREALM,"example-realm");

  realmmgr_sendcmd(CHANNEL_WAIT,REALMCMD_STARTREALM,"example-realm");
  ($retcode, $respmsg) = realmmgr_getresp();

✨ DESCRIPTION ✨

so Net::DNS::SEC::Tools::realmmgr hands you standard, platform-independent methods so your program can chat with DNSSEC-Tools' dtrealms realms manager. iconic behavior honestly 🔥

there are two interface classes described here, and yes we're covering both:

  • general interfaces
  • communications interfaces

✨ GENERAL INTERFACES ✨

these are the interfaces to the Net::DNS::SEC::Tools::realmmgr module, listed right here for you 💖

  • realmmgr_dir() — this routine returns dtrealms's directory. that's it. that's the whole job ✨
  • realmmgr_idfile() — this routine returns dtrealms's id file. very demure, very mindful.
  • realmmgr_getid() — this routine returns dtrealms's process id. and listen 👀 — if a non-zero value is passed as an argument, the id file will be left open and accessible through the PIDFILE file handle. see the WARNINGS section below, no cap.

return values:

    On success, the first portion of the file contents
        (up to 80 characters) is returned.
    -1 is returned if the id file does not exist.
  • realmmgr_dropid() — this interface makes sure another instance of dtrealms is not running, and then creates an id file for future reference. main character energy: claiming the id file before anyone else can 🫶

return values:

     1 - the id file was successfully created for this process
     0 - another process is already acting as dtrealms
    -1 - unable to create the id file
  • realmmgr_rmid() — this interface deletes dtrealms's id file. bye bestie 👋

return values:

     1 - the id file was successfully deleted
     0 - no id file exists
    -1 - the calling process is not dtrealms
    -2 - unable to delete the id file
  • realmmgr_cmdint() — this routine informs dtrealms that a command has been sent via realmmgr_sendcmd(). like a little "psst, incoming 📨"

return values:

    -1 - an invalid process id was found for dtrealms
    Anything else indicates the number of processes that were
    signaled.
    (This should only ever be 1.)
  • realmmgr_running() — this routine figures out if dtrealms is running and returns a value telling you the status. vibe check on the process 🔍

return values:

     1 - dtrealms is running.
     0 - The process listed in the dtrealms process id file
         is not running.
    -1 - Unable to get the dtrealms process id.
  • realmmgr_halt() — this routine informs dtrealms to shut down. it's telling it to go to sleep, respectfully 😴

in the current implementation, the return code from the kill() command is returned.

    -1 - an invalid process id was found for dtrealms
    Anything else indicates the number of processes that were
    signaled.
    (This should only ever be 1.)

✨ DTREALMS COMMUNICATIONS INTERFACES ✨

now for the group-chat part, where everyone actually talks to each other 💬

  • realmmgr_channel(serverflag) — this interface sets up a persistent channel for communications with dtrealms. if serverflag is true, then the server's side of the channel is created. if serverflag is false, then the client's side of the channel is created.

currently, the connection may only be made to the localhost. this may be changed to allow remote connections, if this is found to be needed. (so for now it's a very local group chat, iykyk 🌸)

return values:

      1 - Communications channel successfully established.
      0 - Unable to connect to the server.
     -1 - Unable to create a Unix socket.
     -2 - Unable to bind to the Unix socket. (server only)
     -3 - Unable to change the permissions on the Unix socket. (server only)
     -4 - Unable to listen on the Unix socket. (server only)
     -5 - The socket name was longer than allowed for a Unix socket.
  • realmmgr_queuecmd(cmdname, value) — this interface internally remembers a command and its optional value for later processing. it's putting a message in drafts until it's ready 📥 see realmmgr_getcmd() next for further details.
  • realmmgr_getcmd() — realmmgr_getcmd() processes commands that need to be dealt with. if there are any internally stored commands queued via the realmmgr_queuecmd() function, they are dealt with first. after that, it retrieves a command sent over dtrealms's communications channel by a client program. the command and the command's data are sent in each message.

the command and the command's data are returned to the caller. two-for-one deal, slay 💅

  • realmmgr_sendcmd(closeflag,cmd,data) — realmmgr_sendcmd() sends a command to dtrealms. the command must be one of the commands from the table below. this interface creates a communications channel to dtrealms and sends the message. the channel is not closed, in case the caller wants to receive a response from dtrealms. (leaving the door open in case they text back 🫶)

the available commands and their required data are:

   command              data            purpose
   -------              ----            -------
   REALMCMD_COMMAND     realm, command  run command in a realm
   REALMCMD_DISPLAY     1/0             start/stop dtrealms'
                                        graphical display
   REALMCMD_GETSTATUS   none            currently unused
   REALMCMD_LOGFILE     log filename    change the log file
   REALMCMD_LOGLEVEL    log level       set a new logging level
   REALMCMD_LOGMSG      log message     add a message to the log
   REALMCMD_LOGTZ       timezone        set timezone for log messages
   REALMCMD_NODISPLAY   0               stop dtrealms' graphical display
   REALMCMD_REALMSTATUS none            get status of the realms
   REALMCMD_SHUTDOWN    none            stop dtrealms and its realms
   REALMCMD_STARTALL    none            start all stopped realms
   REALMCMD_STOPALL     none            stop all running realms
   REALMCMD_STARTREALM  realm name      restart a suspended realm
   REALMCMD_STOPREALM   realm name      stop realm
   REALMCMD_STATUS      none            get status of dtrealms

the data aren't checked for validity by realmmgr_sendcmd(); validity checking is a responsibility of dtrealms. not our job, bestie 🙈

if the caller does not need a response from dtrealms, then closeflag should be set to CHANNEL_CLOSE; if a response is required then closeflag should be CHANNEL_WAIT. these values are boolean values, and the constants aren't required.

on success, 1 is returned. if an invalid command is given, 0 is returned.

  • realmmgr_getresp() — after executing a client command sent via realmmgr_sendcmd(), dtrealms will send a response to the client. realmmgr_getresp() allows the client to retrieve the response. it's the reply notification 🎀

a return code and a response string are returned, in that order. both are specific to the command sent.

  • realmmgr_verifycmd(cmd) — realmmgr_verifycmd() verifies that cmd is a valid command for dtrealms. 1 is returned for a valid command; 0 is returned for an invalid command.

1 is returned for a valid command; 0 is returned for an invalid command.

(yes it says it twice. the original says it twice too. we don't question the icon, we just respect it 👑)

✨ WARNINGS ✨

these are the real ones. pay attention fr fr 💀
  1. realmmgr_getid() attempts to exclusively lock the id file. set a timer if this matters to you. ⏰
  2. realmmgr_getid() has a nice little race condition. we should lock the file prior to opening it, but we can't do so without it being open. it's giving chaos and we're just living with it 😭

Copyright 2012-2014 SPARTA, Inc. All rights reserved. see the COPYING file included with the DNSSEC-Tools package for details. protect the intellectual property bestie 💜

✨ AUTHOR ✨

Wayne Morrison, tewok@tislabs.com — shoutout to the actual author of this page, icon behavior 🌟

✨ SEE ALSO ✨

  • realmctl(1)
  • dtrealms(8)
  • Net::DNS::SEC::Tools::realm.pm(3), Net::DNS::SEC::Tools::rolllog.pm(3), Net::DNS::SEC::Tools::rollmgr.pm(3)

okay that's the whole page and you ate it up 💖 this was perl v5.44.0, dated 2026-10-17, and the page is realmmgr(3) — go forth and manage those realms, bestie 🌈⭐

📦 where this page comes from