---
name: "INN::ovsqlite_client"
section: "3pm"
platform: "linux"
package: "inn"
version: "2.7.4-4"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/INN::ovsqlite_client"
---

# INN::ovsqlite\_client(3pm)

Talk to ovsqlite-server from Perl

## NAME

INN::ovsqlite\_client - Talk to ovsqlite-server from Perl

## 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**).

## 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.

## CONSTRUCTOR

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

Croaks on failure.

## 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.

- 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.

- add\_article

  ```
      $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 methods 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.

- 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.

## HISTORY

Initial implementation and documentation written by Bo Lindbergh for InterNetNews.

## SEE ALSO

[perl(1)](/perl/1.md), [ovsqlite-server(8)](/ovsqlite-server/8.md).