---
name: "Text::Iconv"
section: "3pm"
platform: "linux"
package: "perl-text-iconv"
version: "1.7-27"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Text::Iconv"
---

# Text::Iconv(3pm)

Perl interface to iconv() codeset conversion function

## NAME

Text::Iconv - Perl interface to iconv() codeset conversion function

## SYNOPSIS

```
  use Text::Iconv;
  $converter = Text::Iconv->new("fromcode", "tocode");
  $converted = $converter->convert("Text to convert");
```

## DESCRIPTION

The **Text::Iconv** module provides a Perl interface to the **iconv()** function as defined by the Single UNIX Specification.

The **convert()** method converts the encoding of characters in the input string from the *fromcode* codeset to the *tocode* codeset, and returns the result.

Settings of *fromcode* and *tocode* and their permitted combinations are implementation-dependent.  Valid values are specified in the system documentation; the [**iconv**(1)](/iconv/1.md) utility should also provide a **-l** option that lists all supported codesets.

### Utility methods

**Text::Iconv** objects also provide the following methods:

**retval()** returns the return value of the underlying **iconv()** function for the last conversion; according to the Single UNIX Specification, this value indicates "the number of non-identical conversions performed."  Note, however, that iconv implementations vary widely in the interpretation of this specification.

This method can be called after calling **convert()**, e.g.:

```
  $result = $converter->convert("lorem ipsum dolor sit amet");
  $retval = $converter->retval;
```

When called before the first call to **convert()**, or if an error occured during the conversion, **retval()** returns **undef**.

**get\_attr()**: This method is only available with GNU libiconv, otherwise it throws an exception.  The **get\_attr()** method allows you to query various attributes which influence the behavior of **convert()**.  The currently supported attributes are *trivialp*, *transliterate*, and *discard\_ilseq*, e.g.:

```
  $state = $converter->get_attr("transliterate");
```

See [**iconvctl**(3)](/iconvctl/3.md) for details.  To ensure portability to other iconv implementations you should first check for the availability of this method using **eval {}**, e.g.:

```
    eval { $conv->get_attr("trivialp") };
    if ($@)
    {
      # get_attr() is not available
    }
    else
    {
      # get_attr() is available
    }
```

This method should be considered experimental.

**set\_attr()**: This method is only available with GNU libiconv, otherwise it throws an exception.  The **set\_attr()** method allows you to set various attributes which influence the behavior of **convert()**.  The currently supported attributes are *transliterate* and *discard\_ilseq*, e.g.:

```
  $state = $converter->set_attr("transliterate");
```

See [**iconvctl**(3)](/iconvctl/3.md) for details.  To ensure portability to other iconv implementations you should first check for the availability of this method using **eval {}**, cf. the description of **set\_attr()** above.

This method should be considered experimental.

## ERRORS

If the conversion can't be initialized an exception is raised (using **croak()**).

### Handling of conversion errors

*Text::Iconv* provides a class attribute **raise\_error** and a corresponding class method for setting and getting its value.  The handling of errors during conversion depends on the setting of this attribute.  If **raise\_error** is set to a true value, an exception is raised; otherwise, the **convert()** method only returns **undef**.  By default **raise\_error** is false.  Example usage:

```
  Text::Iconv->raise_error(1);     # Conversion errors raise exceptions
  Text::Iconv->raise_error(0);     # Conversion errors return undef
  $a = Text::Iconv->raise_error(); # Get current setting
```

### Per-object handling of conversion errors

As an experimental feature, *Text::Iconv* also provides an instance attribute **raise\_error** and a corresponding method for setting and getting its value.  If **raise\_error** is **undef**, the class-wide settings apply.  If **raise\_error** is 1 or 0 (true or false), the object settings override the class-wide settings.

Consult [**iconv**(3)](/iconv/3.md) for details on errors that might occur.

### Conversion of undef

Converting **undef**, e.g.,

```
  $converted = $converter->convert(undef);
```

always returns **undef**.  This is not considered an error.

## NOTES

The supported codesets, their names, the supported conversions, and the quality of the conversions are all system-dependent.

## AUTHOR

Michael Piotrowski \<mxp@dynalabs.de\>

## SEE ALSO

[**iconv**(1)](/iconv/1.md), [**iconv**(3)](/iconv/3.md)