Cyrus setquota system i/o error

cyrus setquota system i/o error

METHODS Many of the methods have a cyradm-compatible name and a shorter name. In general, methods return undef or empty lists on error. Re: DBERROR error fetching sprers.eu cyrusdb error and "sam sprers.eu cyrus all" > When I try to set quota > I have "setquota: System I/O error" > Hi. 1 Syntax; 2 sprers.eu configuration options; 3 sprers.eu configuration 14 System I/O error on attempted delivery; 15 MUPDATE/IMAP administration.

Cyrus setquota system i/o error - can

Junk

USB2 - Quota enforcement with transacted file systems - Google Patents

This application claims the benefit of U.S. Provisional Application No. 60/,, filed Mar. 30, , entitled QUOTA ENFORCEMENT WITH TRANSACTED FILE SYSTEMS, which application is incorporated herein in its entirety.

Disk capacity continues to increase at a phenomenal rate. At the same time, however, managing the disk space, especially for disks that may be used by more than one user, is becoming more troublesome. Even though disk capacity has increased greatly, it is still finite and may be consumed prematurely or by a small number of users if mismanaged. Thus, administrators and the like are left with the task of determining how much disk space each user is allowed to consume and what to do if a user attempts to exceed the user's disk space. Enforcing quotas of disk space is complicated by transaction-capable file systems.

Briefly, aspects of the subject matter described herein relate enforcing quotas in transactional file systems. In aspects, a filter monitors operations that may affect quota usage/charge of a file system object having a quota allotment.

In doing so, the filter determines a quota value outside of any transaction for the object and a number of quota values associated with transactions affecting the object. The filter receives a request that involves the use of additional quota. The filter then determines whether to allow or fail the request depending on whether enough quota is available to satisfy the request.

This Summary is provided to briefly identify some aspects of the subject matter that is further described below in the Detailed Description. This Summary is not intended to identify key or essential features of the claimed subject matter, nor is it intended to be used to limit the scope of the claimed subject matter.

The phrase “subject matter described herein” refers to subject matter described in the Detailed Description unless the context clearly indicates otherwise. The term “aspects” is to be read as “at least one aspect.” Identifying aspects of the subject matter described in the Detailed Description is not intended to identify key or essential features of the claimed subject matter.

The aspects described above and other aspects of the subject matter described herein are illustrated by way of example and not limited in the accompanying figures in which like reference numerals indicate similar elements and in which:

Exemplary Operating Environment

illustrates an example of a suitable computing system environment on which aspects of the subject matter described herein may be implemented. The computing system environment is only one example of a suitable computing environment and is not intended to suggest any limitation as to the scope of use or functionality of aspects of the subject matter described herein. Neither should the computing environment be interpreted as having any dependency or requirement relating to any one or combination of components illustrated in the exemplary operating environment .

Aspects of the subject matter described herein are operational with numerous other general purpose or special purpose computing system environments or configurations. Examples of well known computing systems, environments, and/or configurations that may be suitable for use with aspects of the subject matter described herein include, but are not limited to, personal computers, server computers, hand-held or laptop devices, multiprocessor systems, microcontroller-based systems, set top boxes, programmable consumer electronics, network PCs, minicomputers, mainframe computers, distributed computing environments that include any of the above systems or devices, and the like.

Aspects of the subject matter described herein may be described in the general context of computer-executable instructions, such as program modules, being executed by a computer. Generally, program modules include routines, programs, objects, components, data structures, and so forth, which perform particular tasks or implement particular abstract data types. Aspects of the subject matter described herein may also be practiced in distributed computing environments where tasks are performed by remote processing devices that are linked through a communications network. In a distributed computing environment, program modules may be located in both local and remote computer storage media including memory storage devices.

With reference to , an exemplary system for implementing aspects of the subject matter described herein includes a general-purpose computing device in the form of a computer . Components of the computer may include, but are not limited to, a processing unit , a system memory , and a system bus that couples various system components including the system memory to the processing unit . The system bus may be any of several types of bus structures including a memory bus or memory controller, a peripheral bus, and a local bus using any of a variety of bus architectures. By way of example, and not limitation, such architectures include Industry Standard Architecture (ISA) bus, Micro Channel Architecture (MCA) bus, Enhanced ISA (EISA) bus, Video Electronics Standards Association (VESA) local bus, and Peripheral Component Interconnect (PCI) bus also known as Mezzanine bus.

Computer typically includes a variety of computer-readable media. Computer-readable media can be any available media that can be accessed by the computer and includes both volatile and nonvolatile media, and removable and non-removable media. By way of example, and not limitation, computer-readable media may comprise computer storage media and communication media. Computer storage media includes both volatile and nonvolatile, removable and non-removable media implemented in any method or technology for storage of information such as computer-readable instructions, data structures, program modules, or other data. Computer storage media includes, but is not limited to, RAM, ROM, EEPROM, flash memory or other memory technology, CD-ROM, digital versatile discs (DVDs) or other optical disk storage, magnetic cassettes, magnetic tape, magnetic disk storage or other magnetic storage devices, or any other medium which can be used to store the desired information and which can be accessed by the computer . Communication media typically embodies computer-readable instructions, data structures, program modules, or other data in a modulated data signal such as a carrier wave or other transport mechanism and includes any information delivery media. The term “modulated data signal” means a signal that has one or more of its characteristics set or changed in such a manner as to encode information in the signal. By way of example, and not limitation, communication media includes wired media such as a wired network or direct-wired connection, and wireless media such as acoustic, RF, infrared and other wireless media. Combinations of any of the above should also be included within the scope of computer-readable media.

The system memory includes computer storage media in the form of volatile and/or nonvolatile memory such as read only memory (ROM) and random access memory (RAM) . A basic input/output system (BIOS), containing the basic routines that help to transfer information between elements within computer , such as during start-up, is typically stored in ROM . RAM typically contains data and/or program modules that are immediately accessible to and/or presently being operated on by processing unit . By way of example, and not limitation, illustrates operating system , application programs , other program modules , and program data .

The computer may also include other removable/non-removable, volatile/nonvolatile computer storage media. By way of example only, illustrates a hard disk drive that reads from or writes to non-removable, nonvolatile magnetic media, a magnetic disk drive that reads from or writes to a removable, nonvolatile magnetic disk , and an optical disc drive that reads from or writes to a removable, nonvolatile optical disc such as a CD ROM or other optical media. Other removable/non-removable, volatile/nonvolatile computer storage media that can be used in the exemplary operating environment include, but are not limited to, magnetic tape cassettes, flash memory cards, digital versatile discs, digital video tape, solid state RAM, solid state ROM, and the like. The hard disk drive is typically connected to the system bus through a non-removable memory interface such as interface , and magnetic disk drive and optical disc drive are typically connected to the system bus by a removable memory interface, such as interface .

The drives and their associated computer storage media, discussed above and illustrated in , provide storage of computer-readable instructions, data structures, program modules, and other data for the computer . In , for example, hard disk drive is illustrated as storing operating system , application programs , other program modules , and program data . Note that these components can either be the same as or different from operating system , application programs , other program modules , and program data . Operating system , application programs , other program modules , and program data are given different numbers herein to illustrate that, at a minimum, they are different copies. A user may enter commands and information into the computer 20 through input devices such as a keyboard and pointing device , commonly referred to as a mouse, trackball or touch pad. Other input devices (not shown) may include a microphone, joystick, game pad, satellite dish, scanner, a touch-sensitive screen of a handheld PC or other writing tablet, or the like. These and other input devices are often connected to the processing unit through a user input interface that is coupled to the system bus, but may be connected by other interface and bus structures, such as a parallel port, game port or a universal serial bus (USB). A monitor or other type of display device is also connected to the system bus via an interface, such as a video interface . In addition to the monitor, computers may also include other peripheral output devices such as speakers and printer , which may be connected through an output peripheral interface .

The computer may operate in a networked environment using logical connections to one or more remote computers, such as a remote computer . The remote computer may be a personal computer, a server, a router, a network PC, a peer device or other common network node, and typically includes many or all of the elements described above relative to the computer , although only a memory storage device has been illustrated in . The logical connections depicted in include a local area network (LAN) and a wide area network (WAN) , but may also include other networks. Such networking environments are commonplace in offices, enterprise-wide computer networks, intranets and the Internet.

When used in a LAN networking environment, the computer is connected to the LAN through a network interface or adapter . When used in a WAN networking environment, the computer typically includes a modem or other means for establishing communications over the WAN , such as the Internet. The modem , which may be internal or external, may be connected to the system bus via the user input interface or other appropriate mechanism. In a networked environment, program modules depicted relative to the computer , or portions thereof, may be stored in the remote memory storage device. By way of example, and not limitation, illustrates remote application programs as residing on memory device . It will be appreciated that the network connections shown are exemplary and other means of establishing a communications link between the computers may be used.

Filters

With contemporary operating systems, such as Microsoft Corporation's Windows® Vista operating system with an underlying file system such as the Windows® NTFS (Windows® NT File System), FAT, CDFS, SMB redirector file system, or WebDav file systems, one or more file system filter drivers may be inserted between the I/O manager that receives user I/O requests and the file system driver. In general, filter drivers (sometimes referred to herein simply as “filters”) are processes that enhance the underlying file system by performing various file-related computing tasks that users desire, including tasks such as passing file system I/O (requests and data) through anti-virus software, file system quota monitors, file replicators, and encryption/compression products.

For example, antivirus products provide a filter that watches I/O to and from certain file types (.exe, .doc, and the like) looking for virus signatures, while file replication products perform file system-level mirroring. Other types of file system filter drivers are directed to system restoration (which backs up system files when changes are about to be made so that the user can return to the original state), disk quota enforcement, backup of open files, undeletion of deleted files, encryption of files, and so forth. Thus, by installing file system filter drivers, computer users can select the file system features they want and need, in a manner that enables upgrades, replacement, insertion, and removal of the components without changing the actual operating system or file system driver code.

The term “process” and its variants as used herein may include one or more traditional processes, threads, components, libraries, objects that perform tasks, and the like. A process may be implemented in hardware, software, or a combination of hardware and software. In an embodiment, a process is any mechanism, however called, capable of or used in performing an action. A process may be distributed over multiple devices or a single device. In one embodiment, an entity comprises a process as defined above. In another embodiment, an entity comprises any one or more objects that is/are capable of performing actions associated with or using or one or more processes.

is a block diagram representing an exemplary arrangement of components of a system that may operate in accordance with aspects of the subject matter described herein. The components include one or more applications , an applications programming interface (API) , an input/output (I/O) manager , a filter manger , a transactional file system , and one or more filters -.

The applications may make file system requests (e.g., via function/method calls) through the API to the I/O manager . The I/O manager may determine what I/O request or requests should be issued to fulfill each request and send each I/O request to the filter manager . The I/O manager may also return data to the applications as operations associated with the file system requests proceed, complete, or abort.

In one implementation, filters comprise objects or the like that when instantiated register (e.g., during their initialization procedure) with a registration mechanism in the filter manager . For efficiency, a filter may register for file system requests in which it may be interested in processing. To this end, as part of registration, each filter notifies the filter manager of the types of I/O requests in which it is interested (e.g., create, read, write, close, rename, and so forth). For example, an encryption filter may register for read and write I/Os, but not for others wherein data does not need to be encrypted or decrypted. Similarly, a quota filter may be interested only in object creates, object deletes, object writes, and other operations that may cause on-disk allocation change of a file.

In addition to specifying the types of I/O requests in which it is interested, a filter may further specify whether the filter should be notified for pre-callbacks and post-callbacks for each of the types of I/O. A pre-callback is called as data associated with an I/O request propagates from the I/O manager towards the transactional file system , while a post-callback is called during the completion of the I/O request as data associated with the I/O request propagates from the transactional file system towards the I/O manager .

From each I/O request, the filter manager may create a data structure in a uniform format suitable for use by the filters -. Hereinafter, this data structure is sometimes referred to as callback data. The filter manager may then call and pass the callback data to each filter that has registered to receive callbacks for the type of I/O received by the filter manager . Any filters registered to receive callbacks for the type of I/Os received by the filter manager are sometimes referred to as mini filters.

Typically, the filter manager passes callback data associated with a particular type of I/O request to each registered filter sequentially in an order in which the registered filters are ordered. For example, if the filters and are registered to receive callbacks for all read I/O requests and are ordered such that the filter is before the filter in processing such requests, then after receiving a read I/O, the filter manager may first call and pass the callback data to the filter and after the filter has processed the callback data, the filter manager may then call and pass the callback data (as modified, if at all) to the filter .

A filter may be attached to one or more volumes. That is, a filter may be registered to be called and receive callback data for I/Os related to only one or more than one volumes.

A filter may generate its own I/O request which may then be passed to other filters. For example, an anti-virus filter may wish to read a file before it is opened. A filter may stop an I/O request from propagating further and may instruct the filter manager to report a status code (e.g., success or failure) for the I/O request. A filter may store data in memory and persist this data on disk. In general, a filter may be created to perform any set of actions that may be performed by a kernel-mode or user-mode process and may be reactive (e.g., wait until it receives I/O requests before acting) and/or proactive (e.g., initiate its own I/O requests or perform other actions asynchronously with I/O requests handled by the I/O manager ).

In one embodiment, filters may be arranged in a stacked manner as illustrated in , which is a block diagram representing another exemplary arrangement of components of a system that may operate in accordance with aspects of the subject matter described herein. In this embodiment, each of the filters - may process I/O requests and pass the requests (modified or unmodified) to another filter or other component in the stack. For example, in response to a read request received from one of the applications , the I/O manager may issue an I/O request and send this request to the filter . The filter may examine the I/O request and determine that the filter is not interested in the I/O request and then pass the I/O request unchanged to the filter . The filter may determine that the filter will perform some action based on the I/O request and may then pass the I/O request (changed or unchanged) to the filter . The filter may determine that the filter is not interested in the I/O request and pass the I/O request to the transactional file system .

After the transactional file system services the I/O request, it passes the results to the filter . Typically, the results pass in an order reverse from that in which the I/O request proceeded (e.g., first to filter , then to filter , and then to filter ). Each of the filters - may examine the results, determine whether the filter is interested in the results, and may perform actions based thereon before passing the results (changed or unchanged) on to another filter or component.

In another embodiment, filters may be arranged in a stacked/managed manner as illustrated in , which is a block diagram representing another exemplary arrangement of components of a system that may operate in accordance with aspects of the subject matter described herein. In this configuration, some filters are associated with a filter manager while other filters are not. Filters that are associated with a filter manager (e.g., filters -) are sometimes referred to herein as mini filters while filters that are not associated with a filter manager (e.g., filters and ) are sometimes referred to herein as legacy filters. The filter manager is placed in a stack with other filters (e.g., filters and ).

It will be readily recognized that filters may be implemented in many other configurations without departing from the spirit or scope of aspects of the subject matter described herein. In some embodiments, a filter comprises any object that examines I/O between an application and a file system and that is capable of changing, completing, or aborting the I/O or performing other actions based thereon.

Returning to , the transactional file system may operate on one or more volumes that may be located locally or remotely to the machine or machines upon which the applications execute.

The transactional file system comprises a mechanism for updating files inside or outside of transactions. Briefly, a process that is accessing an object within a transaction sees that object together with any changes made to the object within the transaction. Processes outside of the transaction do not see the changes made inside of the transaction unless the transaction commits. If a transaction rolls back (also known as “aborts”), the changes made within the transaction are undone and the object returns to its pre-transaction state.

Some transactional file systems allow save points. A save point allows all the files involved in a transaction to be rolled back to the state that existed when the save point was created (without aborting transaction). This may be useful, for example, if a routine called during a transaction makes changes to files involved in the transaction but fails. By restoring to a save point created just before the routine was called, any changes made by the routine may be reversed.

Transactions are well understood by those skilled in the art and will not be described in more detail here.

Quotas

An administrator or the like may desire to impose a quota on a directory or other file system object. A file system object may be a directory, file, some other file system object, and the like. A quota may indicate, among other things, an amount of storage (non-volatile and/or volatile storage) permitted to be consumed by the file system object or by a user. For a file system object that is a file, the quota may indicate how much storage the file is allowed to consume. For a file system object that is a directory, the quota may indicate how much storage may be consumed by all files and directories that are descendants of the directory. A descendant of a directory includes any subdirectories and files in the directory, subdirectories and files in those subdirectories, and so forth. For a user, the quota may indicate how much storage the user is allowed to consume.

A quota filter may enforce quotas on designated file system objects. Certain file system requests (e.g., renames and deletes) may change the file system namespace for the objects monitored by a filter. For example, a quota filter may be configured to enforce a quota of one gigabyte on an object called C:\DIR\QUOTA. The object's name and the quota applicable to the object may be stored in a metadata file which is persisted on non-volatile storage. An application may rename the object C:\DIR to C:\D or may move C:\DIR\QUOTA to C:\QUOTA. To continue enforcing the quota on the QUOTA object, the quota filter may monitor renames and update its metadata file each time a rename affects an object for which the quota filter is enforcing a quota.

In some operating systems, a rename operation may rename an object and/or move the object. Thus, by monitoring rename operations, a filter may capture either a name rename, a move of an object, or both. In operating systems in which renaming the file and moving the file are separate operations, a quota filter may need to monitor both of these operations to enforce quotas.

is a diagram generally representing a portion of a directory structure of an exemplary file system in which aspects of the subject matter described herein may be practiced. The directory structure includes a root directory which has subdirectories Dir1 and Dir5. The directory Dir1 has subdirectories Dir2, Dir3, and Dir4 while the directory Dir5 has subdirectories Dir6, Dir7, and Dir8.

Referring to , the administrator, for example, may set a quota on Dir1 of one megabyte. This means that the combined amount of space used by all descendant files and directories of Dir1 should not exceed one megabyte. For example if the files (not shown) in Dir2 consumed kilobytes of space, the files (not shown) in Dir3 consumed kilobytes of space, the files (not shown) in Dir4 consumed kilobytes of space, and the overhead space to maintain the directories Dir1, Dir2, Dir3, and Dir4 consumed 4 kilobytes of space, the total remaining space before the quota is exceeded is kilobytes.

A quota definition may include quota attributes and actions. Some exemplary quota attributes of a quota include size, directory name, thresholds, a high water mark that maintains the highest quota value charged, a high water time that indicates that last time the high water mark was updated, a last configuration time that indicates when the quota attributes were last modified, a quota tag that comprises a user-defined string that is associated with the quota, and the like. It will be recognized, however, that fewer, more, or other quota attributes may be included in a quota without departing from the spirit or scope of aspects of the subject matter described herein.

As mentioned previously, enforcing quotas becomes more complicated when dealing with a transaction-capable file system. This is in part because a file that is deleted or changed in one part of the transaction may be restored to its original state if the transaction aborts. Similarly, a file that is created during a transaction may be removed if the transaction aborts. Furthermore, entities outside of the transaction are not allowed to see changes made within the transaction until the transaction commits.

In accordance with aspects of the subject matter described herein, quota usage and quota charged are two separate but related concepts. Quota usage for a transaction is the amount of quota that would be used if the transaction were to commit at the time (e.g., just before) the quota usage is determined. For example, if within a transaction, a 10 MB file has been deleted and a 15 MB file has been added, quota usage after the file has been added is 5 MB.

Quota charge for a transaction indicates the maximum quota (i.e., worst case quota) that would be used by changes made within a transaction if the transaction were to commit, abort, or roll back to any save point at a time the quota charge is determined. For example, if a process deletes a 1 MB file during a transaction, quota charge after the delete but before a commit for the transaction would include the 1 MB as the transaction could abort. As another example, if a transaction has multiple save points where delta quota used at each save point is 1 MB, 10 MB, −6 MB, 5 MB, and 3 MB, and the current save point is 3 MB, quota charge for the transaction is 10 MB because the transaction could be rolled back to that save point and then committed. Barring extenuating circumstances, quota charge for a transaction should be greater than or equal to actual quota used within the transaction.

Note that quota usage for a transaction may be indicated by a delta amount that may be positive, zero, or negative. For example, it may be more computationally efficient to use delta amounts to calculate quota usage than to use absolute values. For example, if inside a transaction, a 1 MB file is extended to 4 MB, the delta quota usage for the transaction is 3 MB. As used herein, unless the context indicates otherwise, each time the phrase quota usage is used, in one embodiment it is to be replaced with the phrase delta quota usage while in another embodiment it is to remain as is.

Quota usage for a directory is the amount of quota used for the directory and any of its descendants outside of the context of any transaction. Thought of differently, quota used for the directory and all of its descendants is equivalent to the amount of disk space that the directories and its descendants would use if all transactions operating on the directory and its descendants were to roll back and then the disk space for the directory and its descendants was measured. For example, if a directory includes five files of MB each (outside of transactions) the quota usage for the directory is MB. Even if some of the files are involved in transactions, the quota usage for the directory is MB.

Quota charge for a directory indicates quota used for the directory plus delta quota charge for each transaction that involves a descendent of the directory. For example, if two of the five files above were involved in transactions and one of the transactions had a delta quota charge of 10 MB and the other transaction had a delta quota charge of 20 MB, the quota charge for the directory is MB.

The quota charge for a directory computed above may be enforced outside the context of any transaction and returned in usage queries outside of the context of any transaction. For example, a quota filter may fail I/O requests that would cause quota charge for a directory to exceed a quota allotment for the directory. As another example, if a process outside of a transaction affecting the directory queries for quota available, the quota allotment for the directory minus the quota charge for the directory may be returned.

In one embodiment, a threshold notification may be fired based on quota usage and/or quota charge. A threshold notification is a notification that indicates that a designated value (e.g., a percentage or absolute amount) of disk space (i.e., a “threshold” of disk space) has been exceeded. The notification may be sent to a process that provides notification to a system administrator or the like. Just because a threshold has been exceeded does not necessarily mean that further I/Os that increases quota usage or quota charge are failed as the threshold will almost always be set at a value less than the quota allotment.

Total quota used for a directory depends on whether it is used inside or outside of a transaction that might affect the quota charge of the directory. If the total quota used is queried outside of a transaction then it is equal to the quota charge for a directory. If the total quota used is queried inside of a transaction (e.g., T) that might affect the quota charge of the directory, the total quota used may be computed as the sum of:

1. The sum of quota charges for each transaction except T that affect the quota charge for a directory; and

2. The current quota usage for T.

The total quota used may be enforced inside the context of the transaction T and may be reported in usage queries inside the context of transaction T. For example, if the transaction T requests to extend or create a file and the total quota used exceeds the allotted quota, the request may be failed. If the transaction T queries for quota usage (e.g., to see how much quota is left), the total quota used as computed above may be returned.

In one embodiment, transaction metadata overhead may also be accounted for in quota usage and/or charge. Transactions involve some overhead to allow for rollbacks and crash recovery. For example, a change log may be stored that indicates changes made within the transaction. The change log may consume disk space if not placed in other non-volatile or volatile memory. The amount of disk space consumed by the metadata overhead may also be added to quota usage and/or charge.

In another embodiment, however, transaction metadata overhead is not accounted for in quota usage and/or charge.

To assist with describing tracking quota values in the presence of transaction, the following are defined:

1. Let N be the number of transactions.

2. Let T0 be a non transaction.

3. Let Tk be the kth transaction, 1≦k≦N.

A transactional file system may or may not support save points. When a transactional file system does not support save points or when there are no save points within any transactions, the following may be defined:

1. Let S0 be the quota usage for a directory outside of any transactions.

2. Let Sk be the quota usage for transaction Tk.

3. Let Dk=Sk−S0 be the delta quota usage for the transaction Tk.

Then, the quota charge Q0 for the directory is:

And the total quota used Qk seen within any transaction Tk is:

which may also be rewritten as:
Qk=Q0+Dk−max(0,Dk),1≦k≦N

When a transactional file system supports save points, the following may be defined:

1. Let Nk be the number of save points for the transaction Tk.

2. Let S0 be the quota usage for a directory outside of any transactions.

3. Let Skj be the quota usage for the transaction Tk at the save point j.

4. Let Dkj=Sk−S0 be the delta quota usage for the transaction Tk at the save point j.

5. Let {Dk}={Dk1, Dk2, . . . } be the delta quota usage of all the save points for the transaction Tk.

6. Let Dk be the delta quota usage of the current save point for transaction Tk.

7. Let Wk=max(0, Dk1, Dk2, . . . , Dk) be the worst case delta quota usage for transaction Tk.

Then, the quota charge Q0 for the directory is:

And the total quota used Qk seen within any transaction Tk is:

which may also be rewritten as:
Qk=Q0+Dk−Wk,1≦k≦N

In one embodiment, to track quota usage/charge in the presence of transactions, a quota filter may use two variables. Variables as used herein may include simple variables such as scalar variables and more complex variables such a data structures. One of the variables (e.g., Value) tracks quota usage for the directory (e.g., outside of transactions). Another variable (e.g., TxValue) tracks quota usage a transaction that affects the quota charge of the directory. When a rollback to a save point occurs, the underlying file system is queried to determine the quota usage of the transaction. Below is some exemplary pseudo code:

Note that the size, N, of the TxValue array may be dynamically increased or decreased when a transaction that affects the quota charge of the directory is created, committed, or aborted.

In another embodiment, to track quota usage/charge in the presence of transactions without querying after rolling back to a save point, a quota filter may use other variables. One of the variables (e.g., Value) tracks quota usage for the directory outside of transactions. Another variable (e.g., TxValue) tracks quota usage of a transaction. The TxValue variable may comprise a data structure used to keep track of quota usage within the transaction at the various save points. This data structure may be used when a rollback to a save point occurs as well as being used to compute quota charge for a transaction. Below is some exemplary pseudo code:

Below is some exemplary pseudo code to track quota usage/charge in the presence of transaction save points without querying after rolling back to a save point.

Drafts die "Can't open sprers.eu: $!\n" );

You can also:

use Mail::IMAPClient; # set $user, $pass, and $server here open(DBG,">sprers.eu") or die "Can't open sprers.eu: $!\n"; my $imap = Mail::IMAPClient->new( User=>$user, Password=>$pass, Server=>$server, Debug=> 1, Debug_fh => *DBG );

Specifying this parameter is not very useful unless "Debug" is set to a true value.

Domain

The Domain parameter is used by the NTLM "Authmechanism". The domain is an optional parameter for NTLM authentication.

EnableServerResponseInLiteral

Removed in _01 (now autodetect)

Fast_io

Example:

$Fast_io = $imap->Fast_io(); # or: $imap->Fast_io($true_or_false);

The Fast_io parameter controls whether or not the Mail::IMAPClient object will attempt to use non-blocking I/O on the IMAP socket. It is turned on by default (unless the caller provides the socket to be used).

See also "Buffer".

Folder

Example:

$Folder = $imap->Folder(); # or: $imap->Folder($new_value);

The Folder parameter returns the name of the currently-selected folder (in case you forgot). It can also be used to set the name of the currently selected folder, which is completely unnecessary if you used the "select" method (or "select"'s read-only equivalent, the "examine" method) to select it.

Note that setting the Folder parameter does not automatically select a new folder; you use the "select" or "examine" object methods for that. Generally, the Folder parameter should only be queried (by using the no-argument form of the Folder method). You will only need to set the Folder parameter if you use some mysterious technique of your own for selecting a folder, which you probably won't do.

Ignoresizeerrors

Certain (caching) servers, like Exchange , often report the wrong message size. Instead of chopping the message into a size that it fits the specified size, the reported size will be simply ignored when this parameter is set to 1.

Keepalive

Some firewalls and network gear like to timeout connections prematurely if the connection sits idle. The Keepalive parameter, when set to a true value, affects the behavior of "new" and "Socket" by enabling SO_KEEPALIVE on the socket.

Version note: attribute added in Mail::IMAPClient

Maxcommandlength

The Maxcommandlength attribute is used by fetch() to limit length of commands sent to a server. The default is chars, following the recommendation of RFC section

Note: this attribute should also be used for several other methods but this has not yet been implemented please feel free to file bugs for methods where you run into problems with this.

This attribute should remove the need for utilities like imapsync to create their own split() functions and instead allows Mail::IMAPClient to DWIM.

In practice, this parameter has proven to be useful to overcome a limit of octets for UW-IMAPD and octets for Courier/Cyrus IMAP servers.

Version note: attribute added in Mail::IMAPClient

Maxtemperrors

Example:

$Maxtemperrors = $imap->Maxtemperrors(); # or: $imap->Maxtemperrors($number);

The Maxtemperrors parameter specifies the number of times a read or write operation is allowed to fail on a "Resource Temporarily Available" (e.g. EAGAIN) error. The default setting is undef which means there is no limit.

Setting this parameter to the string "unlimited" (instead of undef) to ignore "Resource Temporarily Unavailable" errors is deprecated.

Note: This setting should be used with caution and may be removed in a future release. Setting this can cause methods to return to the caller before data is received (and then handled) properly thereby possibly then leaving the module in a bad state. In the future, this behavior may be changed in an attempt to avoid this situation.

Password

Example:

$Password = $imap->Password(); # or: $imap->Password($new_value);

Specifies the password to use when logging into the IMAP service on the host specified in the Server parameter as the user specified in the User parameter. Can be supplied with the new method call or separately by calling the Password object method.

If Server, User, and Password are all provided to the "new" method, then the newly instantiated object will be connected to the host specified in Server (at either the port specified in Port or the default port ) and then logged on as the user specified in the User parameter (using the password provided in the Password parameter). See the discussion of the "new" method, below.

Peek

Example:

$Peek = $imap->Peek(); # or: $imap->Peek($true_or_false);

Setting Peek to a true value will prevent the "body_string", "message_string" and "message_to_file" methods from automatically setting the \Seen flag. Setting "Peek" to 0 (zero) will force "body_string", "message_string", "message_to_file", and "parse_headers" to always set the \Seen flag.

The default is to set the seen flag whenever you fetch the body of a message but not when you just fetch the headers. Passing undef to the eponymous Peek method will reset the Peek parameter to its pristine, default state.

Port

Example:

$Port = $imap->Port(); # or: $imap->Port($new_value);

Specifies the port on which the IMAP server is listening. A default value of (if "Ssl" is true) or is set during a call to "connect" if no value is provided by the caller. This argument can be supplied with the "new" method call or separately by calling the "Port" object method.

Prewritemethod

Prewritemethod parameter should contain a reference to a subroutine that will do "special things" to data before it is sent to the IMAP server (such as encryption or signing).

This method will be called immediately prior to sending an IMAP client command to the server. Its first argument is a reference to the Mail::IMAPClient object and the second argument is a string containing the command that will be sent to the server. Your Prewritemethod should return a string that has been signed or encrypted or whatever; this returned string is what will actually be sent to the server.

Your Prewritemethod will probably need to know more than this to do whatever it does. It is recommended that you tuck all other pertinent information into a hash, and store a reference to this hash somewhere where your method can get to it, possibly in the Mail::IMAPClient object itself.

Note that this method should not actually send anything over the socket connection to the server; it merely converts data prior to sending.

See also "Readmethod".

Ranges

Example:

$imap->Ranges(1); # or: my $search = $imap->search(@search_args); if ( $imap->Ranges) { # $search is a MessageSet object print "This is my condensed search result: $search\n"; print "This is every message in the search result: ", join(",",@$search),"\n; }

If set to a true value, then the "search" method will return a Mail::IMAPClient::MessageSet object if called in a scalar context, instead of the array reference that fetch normally returns when called in a scalar context. If set to zero or if undefined, then search will continue to return an array reference when called in scalar context.

This parameter has no affect on the search method when search is called in a list context.

RawSocket

Example:
$socket = $imap->RawSocket;
# or:
$imap->RawSocket($socketh);

The RawSocket method can be used to obtain the socket handle of the current connection (say, to do I/O on the connection that is not otherwise supported by Mail::IMAPClient) or to replace the current socket with a new handle (for instance an SSL handle, see IO::Socket::SSL, but be sure to see the "Socket" method as well).

If you supply a socket handle yourself, either by doing something like:

$imap=Mail::IMAPClient->new(RawSocket => $sock, User => );

or by doing something like:

$imap = Mail::IMAPClient->new(User => $user, Password => $pass, Server => $host); # blah blah blah $imap->RawSocket($ssl);

then it will be up to you to establish the connection AND to authenticate, either via the "login" method, or the fancier "authenticate", or, since you know so much anyway, by just doing raw I/O against the socket until you're logged in. If you do any of this then you should also set the "State" parameter yourself to reflect the current state of the object (i.e. Connected, Authenticated, etc).

Note that no operation will be attempted on the socket when this method is called. In particular, after the TCP connections towards the IMAP server is established, the protocol mandates the server to send an initial greeting message, and you will have to explicitly cope with this message before doing any other operation, e.g. trying to call "login". Caveat emptor.

For a more DWIM approach to setting the socket see "Socket".

Readmethod

Example:

$imap->Readmethod( # IMAP, HANDLE, BUFFER, LENGTH, OFFSET sub { my ( $self, $handle, $buffer, $count, $offset ) = @_; my $rc = sysread( $handle, $$buffer, $count, $offset ); # do something useful here } );

Readmethod should contain a reference to a subroutine that will replace sysread. The subroutine will be passed the following arguments: first the used Mail::IMAPClient object. Second, a reference to a socket. Third, a reference to a scalar variable into which data is read (BUFFER). The data placed here should be "finished data", so if you are decrypting or removing signatures then be sure to do that before you place data into this buffer. Fourth, the number of bytes requested to be read; the LENGTH of the request. Lastly, the OFFSET into the BUFFER where the data should be read. If not supplied it should default to zero.

Note that this method completely replaces reads from the connection to the server, so if you define one of these then your subroutine will have to actually do the read. It is for things like this that we have the "Socket" parameter and eponymous accessor method.

Your Readmethod will probably need to know more than this to do whatever it does. It is recommended that you tuck all other pertinent information into a hash, and store a reference to this hash somewhere where your method can get to it, possibly in the Mail::IMAPClient object itself.

See also "Prewritemethod".

Readmoremethod

Readmoremethod should contain a reference to a subroutine that will replace/enhance the behavior of the internal _read_more() method. The subroutine will be passed the following arguments: first the used Mail::IMAPClient object. Second, a reference to a socket. Third, a timeout value which is used as the timeout value for CORE::select() by default. Depending upon changes/features introduced by Readmethod changes may be required here.

Version note: attribute added in Mail::IMAPClient

Reconnectretry

If an IMAP connection sits idle too long, the connection may be closed by the server or firewall, etc. The Reconnectretry parameter, when given a positive integer value, will cause Mail::IMAPClient to retrying IMAP commands up to X times when an EPIPE or ECONNRESET error occurs. This is disabled (0) by default.

See also "Keepalive"

Version note: attribute added in Mail::IMAPClient

Server

Example:

$Server = $imap->Server(); # or: $imap->Server($hostname);

Specifies the hostname or IP address of the host running the IMAP server. If provided as part of the "new" method call, then the new IMAP object will automatically be connected at the time of instantiation. (See the "new" method, below.) Can be supplied with the "new" method call or separately by calling the Server object method.

Showcredentials

Normally debugging output will mask the login credentials when the plain text login mechanism is used. Setting Showcredentials to a true value will suppress this, so that you can see the string being passed back and forth during plain text login. Only set this to true when you are debugging problems with the IMAP LOGIN command, and then turn it off right away when you're finished working on that problem.

Example:

print "This is very risky!\n" if $imap->Showcredentials(); # or: $imap->Showcredentials(0); # mask credentials again

Socket

PLEASE NOTE The semantics of this method has changed as of version _04 of this module. If you need the old semantics use "RawSocket".

Example:

$Socket = $imap->Socket(); # or: $imap->Socket($socket_fh);

The Socket method can be used to obtain the socket handle of the current connection. This may be necessary to do I/O on the connection that is not otherwise supported by Mail::IMAPClient) or to replace the current socket with a new handle (for instance an SSL handle, see IO::Socket::SSL).

If you supply a socket handle yourself, either by doing something like:

$imap = Mail::IMAPClient->new( Socket => $sock, User => );

or by doing something like:

$imap = Mail::IMAPClient->new( User => $user, Password => $pass, Server => $host ); $imap->Socket($ssl);

then you are responsible for establishing the connection, i.e. make sure that $ssl in the example is a valid and connected socket.

This method is primarily used to provide a drop-in replacement for IO::Socket::(INET METHODS awk '{ email=$9; if (email&#;!~ /@/) { email=$8; } total[email] = total[email] + 1; if ($0 ~ /plaintext\+TLS/) { ssl[email]=ssl[email]+1; } else if ($0 ~ /PLAIN\+TLS/) { ssl[email]=ssl[email]+1; } } END { print "total = " length(total); print "ssl = " length(ssl); }'

Assorted Links

Cyrus: sieve scripts in shared folders