/ 
POSIX-Wide-12
River stage one • 3 direct dependents • 3 total dependents
/ POSIX::Wide

NAME

POSIX::Wide -- POSIX functions returning wide-char strings

SYNOPSIS

use POSIX::Wide;
print POSIX::Wide::strerror(2),"\n";
print POSIX::Wide::strftime("%a %d-%b\n",localtime());

DESCRIPTION

This is a few of the POSIX module functions adapted to return Perl wide-char strings instead of locale charset byte strings. This is good if working with wide-chars internally (and converting on I/O).

The locale charset is determined by Encode::Locale.

EXPORTS

Nothing is exported by default, but each of the functions and the $ERRNO and $EXTENDED_OS_ERROR variables can be imported in usual Exporter style. Eg.

use POSIX::Wide 'strftime', '$ERRNO';

There's no :all tag, as not sure if it would best import just the new funcs, or get everything from POSIX.

FUNCTIONS

$str = POSIX::Wide::localeconv ($format, ...)

Return a hashref of locale information

{ decimal_point => ...,
  grouping      => ...
}

Text field values are wide chars. Non-text fields like grouping and number fields like frac_digits are unchanged.

$str = POSIX::Wide::perror ($message)

Print $message and errno string $! to STDERR, with wide-chars for the errno string.

$message: $!\n
$str = POSIX::Wide::strerror ($errno)

Return a descriptive string for a given $errno number.

$str = POSIX::Wide::strftime ($format, $sec, $min, $hour, $mday, $mon, $year, ...)

Format a string of date-time parts. $format and the return are wide-char strings.

The current implementation passes ASCII parts of $format, including the "%" formatting directives, to strftime(). This means $format can include characters which might not exist in the locale charset.

($std_name, $dst_name) = POSIX::Wide::tzname ()

Return the tzname[] strings for standard time and daylight savings time as wide char strings.

The POSIX spec is that these should only have characters from the "portable character set", so normally the plain bytes of POSIX::tzname should suffice. POSIX::Wide::tzname can be used if someone might be creative in their TZ setting.

VARIABLES

$num = $POSIX::Wide::ERRNO + 0
$str = "$POSIX::Wide::ERRNO"

A magic dual string+number variable like $! but giving the string form as wide-chars (see "$ERRNO" in perlvar).

$num = $POSIX::Wide::EXTENDED_OS_ERROR + 0
$str = "$POSIX::Wide::EXTENDED_OS_ERROR"

A magic dual string+number variable like $^E but giving the string form as wide-chars (see "$EXTENDED_OS_ERROR" in perlvar).

The current implementation assumes $^E is locale bytes (if it isn't already wide). This is true of POSIX but not absolutely sure for MacOS and VMS.

CONFIGURATION

@LOCALECONV_STRING_FIELDS

An array of the field names from localeconv() which are converted to wide-char strings, if the fields exist. Currently these are

decimal_point
thousands_sep
int_curr_symbol
currency_symbol
mon_decimal_point
mon_thousands_sep
positive_sign
negative_sign

The POSIX module omits from its return any fields which are empty strings, and apparently there's no mon_thousands_sep in some early DJGPP.

WITH Errno::AnyString

Custom error strings set into $! by Errno::AnyString work with all of strerror(), perror() and $ERRNO above. Custom error numbers registered with Errno::AnyString can be turned into strings with strerror() too.

Any non-ASCII in such a string should be locale bytes the same as normal $! strings. If $! is already a wide character string then <POSIX::Wide> will return it unchanged. Whether wide strings from $! would well with other code is another matter.

OTHER WAYS TO DO IT

Glib::Utils strerror() gives a wide char string similar to POSIX::Wide::strerror() above if you're using Glib.

Glib also has a g_date_strftime(), which is not wrapped as of Perl-Glib 1.220, giving a utf8 strftime() similar to POSIX::Wide::strftime() above, but only for a date, not a date and time together.

SEE ALSO

POSIX, Encode::Locale, Glib::Utils (which includes a wide strsig())

HOME PAGE

http://user42.tuxfamily.org/posix-wide/index.html

LICENSE

POSIX-Wide is Copyright 2008, 2009, 2010, 2011, 2014, 2024 Kevin Ryde

POSIX-Wide is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

POSIX-Wide is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with POSIX-Wide. If not, see http://www.gnu.org/licenses/.