---
name: "Cyrus::SIEVE::managesieve"
section: "3pm"
platform: "linux"
package: "libcyrus-imap-perl"
version: "3.10.2-1+deb13u2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Cyrus::SIEVE::managesieve"
---

# Cyrus::SIEVE::managesieve(3pm)

Perl client for the SIEVE protocol

## NAME

Cyrus::SIEVE::managesieve - Perl client for the SIEVE protocol

## SYNOPSIS

```
  use Cyrus::SIEVE::managesieve;
```

## DESCRIPTION

This is a Perl module which provides a client for the SIEVE protocol. It supports SASL authentication and communication encryption, using the Cyrus SASL infrastructure.

It provides the following functions.

- sieve\_get\_handle($servername, &username\_cb, &authname\_cb, &password\_cb, &realm\_cb)

  Creates and returns a new Sieve object which can be used for communicating with the SIEVE server.  The server is connected to and a login sequence is performed, using some combination of the given callbacks to fetch from the calling program any data needed for authentication.

  The *servername* may take any of the forms

  - *hostname*

    - *hostname*:*port*

    - *ipv4address*

    - *ipv4address*:*port*

    - \[*ipv6address*\]

    - \[*ipv6address*\]:*port*

    If not explicitly specified in the *servername*, the port defaults to the port named "sieve" in the client machine's service database (for example the `"/etc/services"` files), or 4190.

  All the callbacks are called with the following arguments

  `$string` = callback($which, `$prompt`);

  where *which* is one of the strings `"username"`, `"authname"`, `"getpass"`, or `"realm"` respectively, and *prompt* is a human-readable English language prompt string for the user's benefit. Each callback should return a string containing the required information.

  The function will return *undef* on error, use *sieve\_get\_global\_error* to get a description of the error.

- sieve\_get\_error($sieveobj)

  Returns a human-readable English language string describing the last error encountered on the object *$sieveobj*.

- **sieve\_get\_global\_error()**

  Returns a human-readable English language string describing the last error encountered while creating a Sieve object.

- sieve\_logout($sieveobj)

  Log out from the SIEVE server.  The *$sieveobj* will become unusable.

- sieve\_put\_file($sieveobj, $filename)

  Installs a SIEVE script contained in a local file named by *$filename* to the server.  The name of the script on the server will be the basename of *$filename*.  Returns zero on success and non-zero on failure.

- sieve\_put\_file\_withdest($sieveobj, $filename, $destname)

  Like *sieve\_put\_file* but also specifies the name of the file on the server.  Any directory part of *$destname* is ignored.

- sieve\_put($sieveobj obj, $name, $data)

  Installs a SIEVE script contained in the scalar `$data` to the server, with the script name *$name*.  Returns zero on success and non-zero on failure.

- sieve\_delete($sieveobj obj, $name)

  Removes a SIEVE script from the server.  Returns zero on success and non-zero on failure.

- sieve\_list($sieveobj obj, &callback)

  Lists existing SIEVE scripts on the server.  The *&callback* returns no value and is called once for each script on the server, with arguments

  callback($name, `$is_active`)

  *sieve\_list* returns zero on success and non-zero on failure.

- sieve\_activate($sieveobj, $name)

  Makes the script named *$name* the active script on the server.  Only one script is active at a time; activating a script de-activates any others.  Returns zero on success and non-zero on failure.

- sieve\_get($sieveobj, $name, $output)

  Retrieves the SIEVE script named \<$name\> from the server, and stores it in the scalar *$output*.  Returns zero on success and non-zero on failure.

## AUTHOR

T. Martin, tmartin@andrew.cmu.edu

## SEE ALSO

RFC5804, A Protocol for Remotely Managing Sieve Scripts.