GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
Prima::Utils(3) User Contributed Perl Documentation Prima::Utils(3)

Prima::Utils - miscellanneous routines

The module contains miscellaneous helper routines.

alarm $TIMEOUT, $SUB, @PARAMS
Calls SUB with PARAMS after TIMEOUT milliseconds.
beep [ FLAGS = mb::Error ]
Invokes the system-depended sound and/or visual bell, corresponding to one of following constants:

        mb::Error
        mb::Warning
        mb::Information
        mb::Question
    
get_gui
Returns one of "gui::XXX" constants, reflecting the graphic user interface used in the system:

        gui::Default
        gui::PM
        gui::Windows
        gui::XLib
        gui::GTK
    
get_os
Returns one of "apc::XXX" constants, reflecting the platfrom. Currently, the list of the supported platforms is:

        apc::Win32
        apc::Unix
    
ceil DOUBLE
Obsolete function.

Returns stdlib's ceil() of DOUBLE

find_image PATH
Converts PATH from perl module notation into a file path, and searches for the file in @INC paths set. If a file is found, its full filename is returned; otherwise "undef" is returned.
floor DOUBLE
Obsolete function.

Returns stdlib's floor() of DOUBLE

last_error
Returns last system error, if any
path [ FILE ]
If called with no parameters, returns path to a directory, usually ~/.prima, that can be used to contain the user settings of a toolkit module or a program. If FILE is specified, appends it to the path and returns the full file name. In the latter case the path is automatically created by "File::Path::mkpath" unless it already exists.
post $SUB, @PARAMS
Postpones a call to SUB with PARAMS until the next event loop tick.
query_drives_map [ FIRST_DRIVE = "A:" ]
Returns anonymous array to drive letters, used by the system. FIRST_DRIVE can be set to other value to start enumeration from. Win32 can probe removable drives there, so to increase responsiveness of the function it might be reasonable to call it with FIRST_DRIVE set to "C:" .

If the system supports no drive letters, empty array reference is returned ( unix ).

query_drive_type DRIVE
Returns one of "dt::XXX" constants, describing the type of drive, where DRIVE is a 1-character string. If there is no such drive, or the system supports no drive letters ( unix ), "dt::None" is returned.

        dt::None
        dt::Unknown
        dt::Floppy
        dt::HDD
        dt::Network
        dt::CDROM
        dt::Memory
    
sound [ FREQUENCY = 2000, DURATION = 100 ]
Issues a tone of FREQUENCY in Hz with DURATION in milliseconds.
username
Returns the login name of the user. Sometimes is preferred to the perl-provided "getlogin" ( see "getlogin" in perlfunc ) .
xcolor COLOR
Accepts COLOR string on one of the three formats:

        #rgb
        #rrggbb
        #rrrgggbbb
    

and returns 24-bit RGB integer value.

Since perl win32 unicode support for files is unexistent, Prima has its own parallel set of functions mimicking native functions, ie "open", "chdir" etc. This means that files with names that cannot be converted to ANSI (ie user-preferred) codepage are not visible in perl, but the functions below mitigate that problem.

The following fine points need to be understood prior to using these functions though:

  • Prima makes a distinction whether scalars have their utf8 bit set or not throughout the whole toolking. For example, text output in both unix and windows is different depending on the bit, treating non-utf8-bit text as locale-specific, and utf8-bit text as unicode. The same model is applied for the file systems.
  • Perl implementation for native Win32 creates virtual environments for each thread, keeping current directory, environment variables, etc. This means that under Win32 calling "Prima::Utils::chdir" will NOT automatically make "CORE::chdir" assume that value, even if the path is convertable to ANSI. Keep that in mind when mixing Prima and core functions. (To add more confusion, under the unix these two chdirs are identical when the path is fully convertable).
  • Under unix, reading entries from environment or file system is opportunistic: if is a valid utf8, then it is a utf8 string. Mostly because .UTF-8 locale are default and standard everywhere. Prima ignores $ENV{LANG} here. This is a bit problematic on Perls under 5.22 as these don't provide means to check for utf8 string validity, so everything will be slapped a utf8 bit on here -- Beware.
  • Setting environment variables may or may not sync with %ENV , depending on how perl is built. Also, %ENV will warn when trying to set scalars with utf-8 bit there.
access PATH, MODE
Same as "POSIX::access".
chdir DIR
Same as "CORE::chdir" but disregards thread local environment on Win32.
chmod PATH, MODE
Same as "CORE::chmod"
closedir, readdir, rewinddir, seekdir, telldir DIRHANDLE
Mimic homonymous perl functions
getcwd
Same as "Cwd::getcwd"
getdir PATH
Reads content of PATH directory and returns array of string pairs, where the first item is a file name, and the second is a file type.

The file type is a string, one of the following:

        "fifo" - named pipe
        "chr"  - character special file
        "dir"  - directory
        "blk"  - block special file
        "reg"  - regular file
        "lnk"  - symbolic link
        "sock" - socket
        "wht"  - whiteout
    

This function was implemented for faster directory reading, to avoid successive call of "stat" for every file.

Also, getdir is consistently inclined to treat filenames in utf8, disregarding both perl unicode settings and the locale.

getenv NAME
Reads directly from environment, possibly bypassing %ENV , and disregarding thread local environment on Win32.
link OLDNAME, NEWNAME
Same as "CORE::link".
local2sv TEXT
Converts 8-bit text into either 8-bit non-utf8-bit or unicode utf8-bit string. May return undef on memory allocation failure.
mkdir DIR, [ MODE = 0666 ]
Same as "CORE::mkdir".
open_file PATH, FLAGS
Same as "POSIX::open"
open_dir PATH
Returns directory handle to be used on "readdir", "closedir", "rewinddir", "telldir", "seekdir".
rename OLDNAME, NEWNAME
Same as "CORE::rename"
rmdir PATH
Same as "CORE::rmdir"
setenv NAME, VAL
Directly sets environment variable, possibly bypassing %ENV , depending on how perl is built. Also disregards thread local environment on Win32.

Note that effective synchronization between this call and %ENV is not always possible, since Win32 perl implementation simply does not allow that. One is advised to assign to %ENV manually, but only if both NAME and VAL don't have their utf8 bit set, otherwise perl will warn about wide characters.

stat PATH
Same as "CORE::stat", except where there is sub-second time resolution provided, returns atime/mtime/ctime entries as floats, same as "Time::HiRes::stat".
sv2local TEXT, FAIL_IF_CANNOT = 1
Converts either 8-bit non-utf8-bit or unicode utf8-bit string into a local encoding. May return undef on memory allocation failure, or if TEXT contains unconvertible characters when FAIL_IF_CANNOT = 1
unlink PATH
Same as "CORE::unlink".
utime ATIME, MTIME, PATH
Same as "CORE::utime", except where there is sub-second time resolution provided, accepts atime/mtime/ctime entries as floats, same as "Time::HiRes::utime".

Dmitry Karasik, <dmitry@karasik.eu.org>.

Prima, Prima::sys::FS.
2022-04-07 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.