start page | rating of books | rating of authors | reviews | copyrights

Book HomeJava and XSLTSearch this book

16.2. The Mail Modules

The Mail modules operate at a higher level than the Net modules, interacting with external mail packages such as mail, mailx, sendmail, or a POP3 server in the case of Net::POP3. This section describes some of the MailTools modules, Mail::Folder, and the other mail-related modules that were mentioned at the beginning of this chapter.

16.2.1. Send Email with Mail::Mailer

The Mail::Mailer module interacts with external mail programs. When you use Mail::Mailer or create a new Mail::Mailer object, you can specify which mail program you want your program to talk to:

use Mail::Mailer qw(mail);

Another way to specify the mailer is:

use Mail::Mailer;
$type = 'sendmail';
$mailprog = Mail::Mailer->new($type);

in which $type is the mail program. Once you've created a new object, use the open function to send the message headers to the mail program as a hash of key/value pairs, in which each key represents a header type, and the value is the value of that header:

# Mail headers to use in the message
%headers = (
    'To' => '[email protected]',
    'From' => '[email protected]',
    'Subject' => 'working?'
);

This code represents headers in which the recipient of the mail message is [email protected], the mail was sent from [email protected], and the subject of the mail message is working?.

Once %headers has been defined, it is passed to open:

$mailprog->open(\%headers);

You then send the body of the message to the mail program:

print $mailprog "This is the message body.\n";

Close the program when the message is finished:

$mailprog->close;

A practical example of using Mail::Mailer might be a command line-driven application that works much like the Unix mail program, either reading STDIN until end-of-file or mailing a file specified on the command line.

Mail::Mailer uses the environment variable PERL_MAILERS to augment or modify the built-in mailer selection. PERL_MAILERS is specified in the following format:

"type1:mailbinary1;mailbinary2;...:type2:mailbinaryX;...:..."

The possible types are listed for the new method below.

The following methods are defined in Mail::Mailer.

new

$mailer = new Mail::Mailer [type, command]

Constructor. Creates a new Mailer object representing the message to be sent. If the optional arguments are specified, the value of commanddepends on type, which can be one of:

mail
Uses the Unix mail program. command is the path to mail. The module searches for mailx, Mail, and mail, in that order.

sendmail
Uses the sendmail program. command is the path to sendmail.

test
Used for debugging. Calls /bin/echo to display the data, but doesn't actually send any mail. command is ignored, if specified.

If no arguments are specified, the Mailer object searches for executables in the above order and uses the first one found as the default mailer.

close

$mailer->close

Closes the mail program.

open

$mailer->open(\%hashref)

Sends message headers to the mail program. The headers are passed via a reference to a hash, in which each key is the name of a header, and the value is the contents of the header field. The value can be either a scalar or a reference to an array of scalars.

16.2.2. Better Header Control with Mail::Send

Mail::Send is built on top of Mail::Mailer, which means that you can also choose the mail program that sends the mail. Mail::Send has implemented the methods to, cc, bcc, and subject to replace the %headers hash used in Mail::Mailer.

Mail::Send uses the open method to open the mail program for output; it is built on Mail::Mailer's new method, so that:

# Start mailer and output headers
$fh = $msg->open('sendmail');

serves the same purpose as:

# Use sendmail for mailing
$mailer = Mail::Mailer->new('sendmail)';

This code tells Mail::Send to use sendmail as the mail program.

Mail::Send also provides the set and add functions, which assign a value to a header tag and append a value to a header tag, respectively. The set function takes two arguments—a header tag and a value—and is used like this:

$msg->set($scalar, @array);

Therefore, to address a message to [email protected]:

$msg->set('To', '[email protected]');

The above sets the To header to [email protected]; however, the following sets the To header to [email protected] and [email protected] because they represent an array of values:

$msg->set('To', ('[email protected]', '[email protected]'));

You might think that you could use the set function as follows to add multiple values to a header value:

$msg->set('To', '[email protected]');
$msg->set('To', '[email protected]');

However, set doesn't append information from one call to another, and the above example would send the mail only to [email protected]. To append a name to the To header, use the add method. For example:

$msg->add('To', '[email protected]');
$msg->add('To', '[email protected]');

The following methods are defined for Mail::Send.

new

$msg = new Mail::Send [header=>'value'[, ...]]

Constructor. Creates a new Mail::Send object that is the mail message you want to send. You can include values for headers when you create the object, or include them later by calling the appropriate methods.

add

$msg->add(header, values)

Adds a header to the message. header is the header to be added, and values is a list of values to be appended to that header.

bcc

$msg->bcc(values)

Adds a Bcc header containing the mail addresses specified in the list of values to the message. If there already is a Bcc, the new values replace any old values.

cancel

$msg->cancel

Not implemented yet, but will cancel the message.

cc

$msg->cc(values)

Adds a Cc header containing the mail addresses in the list of values to the message. If there already is a Cc, the new values replace any old values.

close

$fh->close

Closes the filehandle $fh (which was returned by open) and sends the message.

delete

$msg->delete(header)

Deletes the header header from the message.

open

$fh = $msg->open

Opens a filehandle for the message object. The filehandle is a Mail::Mailer object.

set

$msg->set(header, values)

Sets the header header to the contents of the array values.

subject

$msg->subject('What this message is about')

Sets the value of the Subject field.

to

$msg->to(values)

Sets the To field to the list of recipients in values.

16.2.3. Handle Folders with Mail::Folder

Once you've begun downloading and reading your mail from a POP server, you might want to save or categorize your messages into folders, which allow you to add, delete, save, and move messages easily. You can do this with Mail::Folder, which was written by Kevin Johnson as an object-oriented, folder-independent interface to mail folders. Mail::Folder supports a number of mailbox formats with the following interfaces:

Mail::Folder::Emaul
A folder interface somewhat similar to MH.

Mail::Folder::Maildir
An interface to maildir folders.

Mail::Folder::Mbox
Standard Unix mailbox format.

Mail::Folder::NNTP
The beginnings of an interface to NNTP. Not all the methods are implemented yet.

If you are interested in writing a folder interface, see the documentation for the module. The documentation explains the concepts and issues involved and describes some of the methods you may need to override.

The following methods are defined for Mail::Folder.

new

$folder = new(ftype[, foldername][, options])

Creates a new Mail::Folder object of the specified type. Arguments are:

ftype
The type of folder. Possible values are mbox, maildir, emaul, or NNTP.

foldername
The name of the folder. If present, the open method is called with foldername as the argument.

options
A hash in which the following options may be the keys:

Content-Length
Content-length header is created or updated by append_message and update_message.

Create
If set, the folder is created if it doesn't already exist.

DefaultFolderType
Autodetects folder type if create option is set and AUTODETECT has been set.

DotLock
Uses .lock-style folder locking with the proper folder interface (currently used only with the mbox interface).

Flock
Uses flock-style folder locking with the proper folder interface (currently used only with the mbox interface).

NFSLock
Deals with NFS-style file locking with the proper folder interface and the NFS server in question.

notMUA
If set, makes updates but doesn't save message labels or the current message indicator. If not set (the default), saves labels and the current message indicator as appropriate for the folder interface.

Timeout
Overrides the default timeout value. Specified in seconds. Particularly useful for folder interfaces that involve network communications.

add_label

$folder->add_label(msg_num, label)

Associates the label label with the message msg_num. Returns 1 on success or 0 if the label has a length of 0. Possible values of label are:

deleted
Used by delete_message and sync to process message deletion.

edited
Added by update_message to indicate that the message has been edited.

filed, forwarded, printed, replied
Not acted on.

seen
Message has been viewed by the user. Set by get_message for any message it has retrieve d.

append_message

$folder->append_message(\$mi_ref)

Adds message to a folder. Argument is a reference to a Mail::Internet object.

clear_label

$folder->clear_label(label)

Deletes the association with label for all messages in the folder. Returns the number of messages for which there was an association.

close

$folder->close

Does any necessary housekeeping and closes the folder.

current_message

$folder->current_message([msg_num])

With no argument, returns the message number of the current message in the folder. With an argument, sets the current message number for the folder to msg_num.

debug

$folder->debug([value])

Sets the level of debugging information for the object to value. With no argument, returns the current debugging level.

debug_print

$folder->debug_print(text)

Prints text, plus some additional information, to STDERR.

delete_label

$folder->delete_label(msg_num, label)

Deletes the association of label with msg_num. Returns 1 on success and 0 if there was no association.

delete_message

$folder->delete_message(msgs)

Takes a list of messages, msgs, to be marked for deletion. The messages aren't actually deleted until sync is called.

dup

$folder->dup(msg_num, \$folder_ref)

Copies the message specified by msg_num to the folder referenced by \$folder_ref. Like refile, but doesn't delete the original message. Generates a fatal error if no folder is currently open or if the folder doesn't contain message msg_num.

first_labeled_message

$folder->first_labeled_message(label)

Returns the message number of the first message in the folder that has label associated with it, or 0 if there are none.

first_message

$folder->first_message

Returns the message number of the first message in the folder.

foldername

$folder->foldername

Returns the name of the folder that the object has opened.

get_fields

$folder->get_fields(msg_num, fields)

Retrieves the fields specified in the list fields for message msg_num. If called in list context, returns a list; in scalar context, returns a reference to a list of the fields. Returns the fields in the same order as they were specified.

get_header

$folder->get_header(msg_num)

Extracts a message header; takes one argument: the message number. Returns a reference to a Mail::Header object.

get_message

$folder->get_message(msg_num)

Takes a message number as argument and returns a Mail::Internet object reference to that message, or 0 on failure.

get_message_file

$folder->get_message_file(msg_num)

Like get_message, but returns a filename instead of a Mail::Internet object reference.

get_mime_header

$folder->get_mime_header(msg_num)

Works much like get_header, but returns a reference to a MIME::Head object instead. Takes one argument, the message number.

get_mime_message

$folder->get_mime_message (msg_num[, parserobject][, options])

Returns a MIME::Entity object for the specified message. Calls get_message_file to get a message to parse, creates a MIME::Parser object, and uses that to create the MIME::Entity object. The arguments are:

msg_num
The number of the message.

parserobject
If specified, used instead of internally creating a parser object.

options
Maps onto the equivalent MIME::Parser methods. Specified as key/value pairs, with possible values of: output_dir, output_prefix, output_to_core. See the MIME::Parser documentation for details.

get_option

$folder->get_option(option)

Returns the setting for the specified option, or undef if the option doesn't exist.

inverse_select

$folder->inverse_select(\$func_ref)

Returns a list, in no specific order, of message numbers that do not match a set of criteria. The argument, \$func_ref, is a reference to a function used to determine the criteria. The function is passed a reference to a Mail::Internet object containing only a header.

is_readonly

$folder->is_readonly

Returns 1 if the folder has the readonly attribute set; otherwise, returns 0.

label_exists

$folder->label_exists(msg_num, label)

Returns 1 if label is associated with message msg_num; otherwise, returns 0.

last_labeled_message

$folder->last_labeled_message(label)

Returns the message number of the last message in the folder with the label label associated with it, or 0 if there is no such message number.

last_message

$folder->last_message

Returns the message number of the last message in the folder.

list_all_labels

$folder->list_all_labels

Returns a list, in no specific order, of all labels associated with messages in the folder. If called in scalar context, returns the number of labels associated with the messages.

list_labels

$folder->list_labels(msg_num)

Returns a list, in no specific order, of all labels associated with msg_num. If called in scalar context, returns the number of labels associated with the message.

message_exists

$folder->message_exists(msg_num)

Returns 1 if a message with the number msg_num exists in the folder; otherwise, returns 0.

message_list

$folder->message_list

Returns a list of the message numbers in the folder, in no specific order. The syntax is:

print $folder->message_list."\n"
next_labeled_message

$folder->next_labeled_message(msg_num, label)

Returns the message number of the next message in the folder relative to msg_number that has the label label associated with it, or 0 if there is no such message.

next_message

$folder->next_message([msg_num])

Returns the number of the next message in the folder relative to msg_numif it is specified; otherwise, relative to the current message. Returns 0 if at end of folder.

open

$folder->open(foldername)

If you didn't specify a folder name in the constructor, you need to call the open method, which takes the folder name as an argument and opens the folder. Also sets readonly if the folder is determined to be read-only.

pack

$folder->pack

For formats that allow message number sequences to have gaps, renames the files in the folders to eliminate any such gaps. May result in renumbering some messages.

prev_labeled_message

$folder->prev_labeled_message(msg_num, label)

Returns the message number of the previous message in the folder relative to msg_num that has the label label associated with it, or 0 if there is no such message.

prev_message

$folder->prev_message([msg_num])

Returns the number of the previous message in the folder relative to msg_num if it is specified; otherwise, relative to the current message. Returns 0 if at the beginning of the folder.

qty

$folder->qty

Returns the number of messages in the folder. The syntax is:

print "There are ".$folder->qty." messages in your 
folder\n";
refile

$folder->refile(msg_num, \$fldr_ref)

Moves messages between folders. Takes a message number and folder reference as arguments.

select

$folder->select(\$func_ref)

Returns a list of messages that meet a set of criteria. The argument, \$func_ref, is a reference to a function used to determine the criteria. The function is passed a reference to a Mail::Internet object containing only a header. The list is returned in no specific order.

select_label

$folder->select_label(label)

Returns a list of messages with the label label. If called in scalar context, returns the number of messages that have the label.

set_option

$folder->set_option(option, value)

Sets the specified option to value.

set_readonly

$folder->set_readonly

Sets the readonly attribute for the folder. Once readonly has been set, sync won't perform any updates to the actual folder.

sort

$folder->sort(\$func_ref)

Returns a sorted list of messages. \$func_ref is a reference to a function that is passed two Mail::Header message references and returns an integer less than, equal to, or greater than 0 to indicate the sort order.

sync

$folder->sync

Synchronizes the folder with internal data structures and reads in any new messages since the last open or sync. Does not perform any updates if the readonly attribute has been set.

undelete_message

$folder->undelete_message(msgs)

Unmarks a list of messages, msgs, that have been marked for deletion.

update_message

$folder->update_message(msg_num, \$mref)

Replaces the message specified by msg_num with the contents of the message given by \$mref, which is a reference to a Mail::Internet object.

16.2.4. Handle Messages with Mail::Internet

Mail::Internet implements a number of helpful functions for manipulating a mail message. These include body, print_header, and head. Mail::Internet is built on top of Mail::Header, which parses the header of an email message, and it inherits the Mail::Header constructor style that requires that a file descriptor or reference to an array be used. For example:

@lines = <STDIN>;
$mi_obj = new Mail::Internet([@lines]);

reads a mail message from STDIN (using a reference to an array). The following example reads a mail message from a filehandle, FILE:

open(FILE, "/home/nvp/Mail/nvp");
$mi_obj = new Mail::Internet(\*FILE);
close(FILE);

The print_header function outputs the header of a message to a file descriptor; the default is STDOUT:

open(FILE, "/home/nvp/Mail/nvp");
$mi_obj = new Mail::Internet(\*FILE);
close(FILE);
$mi_obj->print_header(\*STDOUT);

The above example might output:

From nvp Mon Jun  9 00:11:10 1997
Received: (from nvp@localhost) by mail.somename.com (8.8/8.8) id
    AAA03248 for nvp; Mon, 9 Jun 1997 00:11:09 -0500 (EST)
Date: Mon, 9 Jun 1997 00:11:09 -0500 (EST)
From: "Nathan V. Patwardhan" <nvp>
Message-Id: <[email protected]>
To: nvp
Subject: pop test
X-Status:
X-Uid: 1
Status: RO

in which print_body also takes a file descriptor as an argument, but outputs only the body of the message, whereas the print function outputs an entire message.

16.2.5. Mail::Internet Reference

new

$mail = new Mail::Internet ([arg], [options])

Creates a new Mail::Internet object. arg is optional and may be either a file descriptor (a reference to a glob) or a reference to an array. If present, the new object is initialized with headers either from the array or read from the file descriptor. options is a list of options in the form of key/value pairs. Possible options are:

Header
Mail::Internet should not attempt to read a mail header from arg, if it was specified. Value is a Mail::Header object.

Body
Mail::Internet should attempt to read the body from arg, if it was specified. Value is a reference to an array that contains the lines of the message body.

Modify
Reformats the headers if true. Mail::Header option.

MailFrom
Specifies behavior for headers in the form "From ". Mail::Header option. Possible values are:

IGNORE
Ignores and discards the headers

ERROR
Calls die

COERCE
Renames headers to Mail-From

KEEP
Keeps headers as they are

FoldLength
Value is default line length for folding headers. Mail::Header option.

add_signature

$mail->add_signature([file])

Appends a signature to the message. file is a file that contains the signature; if not specified, the file $ENV{HOME}/.signature is checked for a signature.

body

$mail->body(  )

Returns the body of the message as a reference to an array. Each entry in the array represents one line of the message.

escape_from

$mail->escape_from(  )

Inserts a leading > on any line that starts with "From " to avoid the problems that some applications have if a message contains a line starting with "From ".

head

$headobj = $mail->head(  )

Returns the Mail::Header object that holds the headers for the current message.

nntppost

$mail->nntppost([options])

Posts an article via NNTP; requires Net::NNTP. Options are passed as key/value pairs. Available options are:

Debug
Debug value to pass to Net::NNTP

Host
Name of NNTP server to connect to

Port
Port number to connect to on remote host

print_header

$mail->print_header([\*fd])
$mail->print_body([\*fd])
$mail->print([\*fd])

Prints the header, body, or whole message to file descriptor \*fd, which should be a reference to a glob. If the file descriptor is not given, the output is sent to STDOUT:

$mail->print(\*STDOUT);  # Print message to STDOUT
remove_sig

$mail->remove_sig([nlines])

Removes a user's signature from the body of a message. Looks for a line equal to "-- " within the last nlines lines of the message and removes that line and all lines after it. nlinesdefaults to 10.

reply

$reply = $mail->reply(  )

Creates a new object with headers initialized for a reply to the current object and with a body that is an indented copy of the current message.

smtpsend

$mail->smtpsend(  )

Sends the Mail::Internet message via SMTP to all addresses on the To, Cc, and Bcc lines. Finds the SMTP host by trying to connect first to hosts specified in $ENV{SMTPHOSTS}, then to mailhost, and then to localhost.

In a future release of Mail::Internet, smtpsend will be able to take the hostname as a parameter, as nntppost does.

tidy_body

$mail->tidy_body(  )

Removes all leading and trailing lines that contain only whitespace from the message body.

unescape_from

$mail->unescape_from(  )

Removes the escaping added by escape_from.

16.2.6. Parse Email Addresses with Mail::Address

Mail::Address parses RFC 822-compliant mail addresses of the form:

"Full Name or Phrase" <username@host> (Comment Area)

For example, under RFC 822, an address might be represented as:

"Nathan V. Patwardhan" <[email protected]> (No Comment)

or:

"Nathan V. Patwardhan" <[email protected]>

The Mail::Address constructor parses an email address into three parts based on the categories shown above:

$addr = Mail::Address->new("Full Name or Phrase",
                           "username@host",
                           "(Comment Area)");

Mail::Address also outputs portions of the mail address with the functions phrase, address, comment, format, name, host, and user. The phrase, address, and comment functions represent the first, second, and third entities that were passed to the Mail::Address constructor, in which the phrase function:

print $addr->phrase( );

outputs:

Nathan V. Patwardhan

the address function:

print $addr->address( );

outputs:

[email protected]

and the comment function:

print $addr->comment( );

outputs:

No Comment

A real mail address can be "unmangled," or parsed from its [email protected] format, with the user and host functions. The user function removes everything starting with the @ to the end of the address, and host removes everything up to and including the @. Using the previous example of [email protected], the following line:

print $addr->user;

outputs:

nvp

And the following line using the host function:

print $addr->host;

outputs:

[email protected]

16.2.7. Mail::Address Reference

new

$addr = Mail::Address->new(phrase, address[, comment])

Constructor. Creates new Mail::Address object representing an address with the specified elements. In a message, these three elements show up as:

phrase <address> (comment)
address (comment)
parse

Mail::Address->parse(line)

Constructor. Parses the specified line, usually a To, Cc, or Bcc line, and returns a list of extracted Mail::Address objects.

address

$addr->address(  )

Returns the address part of the object.

canon

$addr->canon(  )

Unimplemented, but should return the UUCP canon for the message.

comment

$addr->comment(  )

Returns the comment part of the object.

format

$addr->format(  )

Returns a string representing the address in a form suitable for the To, Cc, or Bcc line of a message

host

$addr->host(  )

Returns the host portion of the address.

name

$addr->name(  )

Takes information contained in the object and uses various heuristics to try to identify the name of the person or group.

path

$addr->path(  )

Unimplemented, but should return the UUCP path for the message.

phrase

$addr->phrase(  )

Returns the phrase part of the object.

user

$addr->user(  )

Returns the user ID portion of the address.

16.2.8. Checking Blacklisted Hosts with Mail::RBL

Mail::RBL eases the task of checking if a given host is in the real-time blackhole list. Mail::RBL does this by speaking directly to the RBL server and searching for a specified host. Ordinarily, you build this functionality into your MTA (sendmail, qmail, Exim, etc.), but if your system administrator hasn't built RBL support into your MTA, you might consider integrating Mail::RBL into your own mail filter.

new(suffix)
Creates a list handle. suffix is required because it denotes the host from which you'll check hostnames.

check($host)
Performs the lookup against the RBL. $host can be a hostname or IP address, without trailing netmasks (represented by a / followed by an octet).

For example:

use Mail::RBL;

my $host = q[some-spammer.domain.here];
my $rbl = Mail::RBL->new('list.org');

if($rbl->check($host)) {
    print "$host is in the RBL, and I won't deliver the mail."
} else {
    # Do something to deliver the email
}

16.2.9. Mail Filtering with Mail::Audit

Mail::Audit is a mail-filtering system for those who want to write good filter rules but choose not to use procmail. It was written to provide flexibility while realizing the strengths of Perl's regular expression engine. Inspired by Tom Christiansen's audit_mail and deliverdb programs, Mail::Audit allows an email message to be logged, examined, routed to another folder or INBOX, resent, or rejected. You should be able to write a simple ruleset or rulesets and put references to it in your .forward file. For example:

use Mail::Audit;

my $m_au = Mail::Audit->new( );

$m_au->reject("Let me call YOU at home!")
    if $m_au =~ /(spammer\@spammer.com|spammer2\@spammer2.com|spammer3\@spammer3.com)/;

$m_au->accept("Majordomo") if $mail->from =~ /Majordomo\@/;

$m_au->accept( );

Mail::Audit implements the following methods.

new

new(%options)

Constructor. Reads a mail message from STDIN (or, if the data option is set, from an array reference) and creates a Mail::Audit object from it. Options include:

log=>logfile
Writes a debugging log.

loglevel=>n
Sets verbosity of the log on a scale of 1 to 4.

noexit=>1
Do not exit after delivering mail.

If you specify a log level without a log file, logging will be written to /tmp/username-audit.log, where username is replaced by your username.

body

body(  )

Returns a reference to an array of lines in the body of the email.

get

get(header)

Retrieves the named header from the mail message.

header

header(  )

Returns the header as a single string.

ignore

ignore(  )

Ignores an email message completely, dumping it into the bit bucket.

pipe

pipe(program)

Opens a pipe to an external program and feeds the message to it.

put

put(header, value)

Inserts a new header into the mail message with the given value.

reject

reject(message)

Rejects an email message, then notifies the sender that the message is undeliverable with message as the reason given.

resend

resend(address)

Bounces the email in its entirety to another address.

tidy

tidy(  )

Tidies up the email as per the Mail::Internet manpage.

xaccept

xaccept(filename)

Writes the incoming (and filtered) mail into a mailbox at filename. If filename is undefined, mail is written to /var/spool/mail/$USER. If you use Maildir instead of mbox-formatted mail, it will deliver the mail in Maildir style.

16.2.10. Alias Manipulation with Unix::AliasFile

While not a member of the Mail umbrella, Unix::AliasFile is an important module since it implements a complete interface to the Unix aliases text file that allows you to query, add, update, and delete aliases. In addition, it has a cleaner interface than Mail::Alias. Unix::AliasFile automatically handles file locking, comma and colon placement, and any other detail that's related to manipulating your Unix mail alias file. For example:

use Unix::AliasFile;

my $aliasfile = '/etc/mail/aliases';
my $uaf = Unix::AliasFile->new($aliasfile);

foreach my $alias $uaf->aliases( ) {
    chomp($alias);
    
    if($uaf->alias($alias) ne "$alias\@yourpopserver.your.domain") {
        # Doesn't exist, so add alias of the form:
        # alias: [email protected]
        
        $uaf->alias($alias, ("$alias\@yourpopserver.your.domain"));
    } else {
        print "I already have $alias that way.\n";
    }
}

$uaf->commit( );
undef $uaf;

Unix::AliasFile implements the following methods.

new

new(filename)

Constructor. Creates a new Unix::AliasFile object.

add_user

add_user(alias, @users)

Adds @users to alias. If a user in @users already exists in alias, duplicates will be ignored. If alias is set to *, @users will be added to every alias.

alias

alias(alias, @users)

Adds, modifies, or returns information about an alias. When only alias is suppled, alias( ) returns a list of all members of an alias, or undef if alias does not exist. If you supply @users, alias will be modified or created if it doesn't already exist.

aliases

aliases(  )

Returns an alphabetized list of all existing aliases. In scalar context, this method returns the total number of aliases.

comment

comment(alias, comment)

Inserts a comment line before alias. comment must begin with #, but a newline will be appended to it. Returns 1 on success and 0 on failure.

commit

commit(  )

Writes the alias file.

delempty

delempty(  )

Deletes all existing aliases that have no members, returning a count of the number of aliases deleted.

delete

delete(alias)

Deletes alias.

remove_user

remove_user(alias, @users)

Removes the list of users from an existing alias. If a user in @usersisn't a member of alias, the removal attempt will be silently ignored. remove_user( ) returns 1 on success and 0 on failure.

rename_user

rename_user(oldname, newname)

Changes one username to another in every alias. Returns the number of aliases affected.

uncomment

uncomment(comment)

Removes the comment from the file that is exactly matched to the supplied text. Returns 1 on success and 0 on failure.



Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.