INN::ovsqlite_client(3pm)

💖 NAME 💖

okay bestie, welcome to INN::ovsqlite_client(3pm) — an InterNetNews Documentation moment — aka the Perl module that talks to ovsqlite-server. It speaks the binary protocol, it has methods for every request type, and it is lowkey the group-chat bridge between your Perl script and the daemon. 💅

✨ SYNOPSIS ✨

           use INN::ovsqlite_client qw(:all);

           my $client = INN::ovsqlite_client::->new(
               port => "/usr/local/news/run/ovsqlite.sock",
           );

           $client->search_group_all(
               groupname => "news.software.nntp",
               low       => 1,
               cols      => search_col_overview,
               errmsg    => my $errmsg,
               callback  => sub {
                   my ($articles) = @_;

                   foreach my $article (@{$articles}) {
                       print $article->{overview};
                   }
                   1;
               },
           );

           defined($errmsg)
             and die "search_group_all: $errmsg";

🌸 DESCRIPTION 🌸

INN::ovsqlite_client implements the binary protocol used to communicate with the ovsqlite-server daemon. It offers one instance method for each request type plus convenience methods for those requests that need to be repeated. See ovsqlite-private.h for details. 🫶

Two examples of use within a Perl script are present in the contrib directory (ovsqlite-dump and ovsqlite-undump). slay.

🎀 EXPORTS 🎀

🌈 tag :search_cols

Flags to select what optional information the search_group method should return. ✨

• search_col_arrived
• search_col_expires
• search_col_token
• search_col_overview

🌈 tag :response_codes

Success responses:

• response_ok
• response_done
• response_groupinfo
• response_grouplist
• response_grouplist_done
• response_artinfo
• response_artlist
• response_artlist_done

Error responses:

• response_error
• response_sequence_error
• response_sql_error
• response_corrupted
• response_no_group
• response_no_article
• response_dup_article
• response_old_article

Fatal error responses:

• response_fatal
• response_bad_request
• response_oversized
• response_wrong_state
• response_wrong_version
• response_failed_auth

🌈 tag :all

All of the above. the whole little family. 💖

🦋 CONSTRUCTOR 🦋

           $client = INN::ovsqlite_client::->new(
               path => $path,
               mode => $mode,         # optional, default 0 (read only)
           );

Croaks on failure. no cap, if it fails it is gonna croak about it. 😭

💅 METHODS 💅

All request methods return the response code and store any error message in the optional errmsg named argument.

🚨 Communication or protocol errors (as opposed to server errors) cause croaks. important vibe check, bestie.

🍓 set_cutofflow

           $code = $client->set_cutofflow(
               cutofflow  => $cutofflow,     # optional, default 0 (false)
               errmsg     => $errmsg,        # optional output
           );

🍓 add_group

           $code = $client->add_group(
               groupname  => $groupname,
               low        => $low,
               high       => $high,
               flag_alias => $flag_alias,
               errmsg     => $errmsg,        # optional output
           );

🍓 get_groupinfo

           $code = $client->get_groupinfo(
               groupname  => $groupname,
               low        => $low,           # optional output
               high       => $high,          # optional output
               count      => $count,         # optional output
               flag_alias => $flag_alias,    # optional output
               errmsg     => $errmsg,        # optional output
           );

🍓 delete_group

           $code = $client->delete_group(
               groupname  => $groupname,
               errmsg     => $errmsg,        # optional output
           );

🍓 list_groups

           $code = $client->list_groups(
               groupid    => $groupid,       # optional in/output, default 0
               readsize   => $readsize,      # optional, default 0x20000
               groups     => $groups,        # output
               errmsg     => $errmsg,        # optional output
           );

$groups is set to a reference to an array of references to hashes with these keys:

• groupname
• low
• high
• count
• flag_alias

🍓 list_groups_all

           $code = $client->list_groups_all(
               callback   => \&callback,
               readsize   => $readsize,      # optional, default 0x20000
               errmsg     => $errmsg,        # optional output
           );

This convenience method calls list_groups repeatedly to fetch information for all groups. The callback function is called with the groups array reference as the only argument. It should return a true value to keep iterating or a false value to terminate. iconic loop behavior, honestly. 🔥

🍓 add_article

heads up bestie: the code block below literally spells it add_artice, so keep that exact spelling. we do not “fix” the sacred text. 💅

           $code = $client->add_artice(
               groupname  => $groupname,
               artnum     => $artnum,
               token      => $token,
               arrived    => $arrived,       # optional, default 0
               expires    => $expires,       # optional, default 0
               overview   => $overview,
               errmsg     => $errmsg,        # optional output
           );

🍓 get_artinfo

           $code = $client->get_artinfo(
               groupname  => $groupname,
               artnum     => $artnum,
               token      => $token,         # output
               errmsg     => $errmsg,        # optional output
           );

🍓 delete_article

           $code = $client->delete_article(
               groupname  => $groupname,
               artnum     => $artnum,
               errmsg     => $errmsg,        # optional output
           );

🍓 search_group

           $code = $client->search_group(
               groupname  => $groupname,
               low        => $low,
               high       => $high,          # optional
               cols       => $cols,          # optional, default 0x00
               readsize   => $readsize,      # optional, default 0x20000
               articles   => $articles,      # output
               errmsg     => $errmsg,        # optional output
           );

$articles is set to a reference to an array of references to hashes with these keys:

• artnum
• arrived
• expires
• token
• overview

🍓 search_group_all

           $code = $client->search_group_all(
               groupname  => $groupname,
               low        => $low,
               high       => $high,          # optional
               cols       => $cols,          # optional, default 0x00
               callback   => \&callback,
               readsize   => $readsize,      # optional, default 0x20000
               errmsg     => $errmsg,        # optional output
           );

This convenience method calls search_group repeatedly to fetch information for all specified articles. The callback function is called with the articles array reference as the only argument. It should return a true value to keep iterating or a false value to terminate. yes bestie, keep it looping or shut it down. 🦋

🍓 start_expire_group

           $code = $client->start_expire_group(
               groupname  => $groupname,
               errmsg     => $errmsg,        # optional output
           );

🍓 expire_group

           $code = $client->expire_group(
               groupname  => $groupname,
               artnums    => \@artnums,
               errmsg     => $errmsg,        # optional output
           );

@artnums must be an array of article numbers.

🍓 finish_expire

           $code = $client->finish_expire(
               errmsg     => $errmsg,        # optional output
           );

🍓 finish_expire_all

           $code = $client->finish_expire_all(
               callback   => \&callback,
               errmsg     => $errmsg,        # optional output
           );

This convenience method calls finish_expire repeatedly until done. The callback function is called with no arguments and should return a true value to keep iterating or a false value to terminate. periodt. ✨

🌟 HISTORY 🌟

Initial implementation and documentation written by Bo Lindbergh for InterNetNews. 👑

🔗 SEE ALSO 🔗

perl(1), ovsqlite-server(8).

---

mwah 💋 signing off with INN 2.7.4 and 2026-06-12 — INN::ovsqlite_client(3pm) ate and left no crumbs. 🎀