.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::LDAP::LDIF 3pm"
.TH Net::LDAP::LDIF 3pm "2012-02-07" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::LDAP::LDIF \- LDIF reading and writing
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Net::LDAP::LDIF;
\&
\& $ldif = Net::LDAP::LDIF\->new( "file.ldif", "r", onerror => \*(Aqundef\*(Aq );
\& while( not $ldif\->eof ( ) ) {
\&   $entry = $ldif\->read_entry ( );
\&   if ( $ldif\->error ( ) ) {
\&     print "Error msg: ", $ldif\->error ( ), "\en";
\&     print "Error lines:\en", $ldif\->error_lines ( ), "\en";
\&   } else {
\&     # do stuff
\&   }
\& }
\& $ldif\->done ( );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBNet::LDAP::LDIF\fR provides a means to convert between
Net::LDAP::Entry objects and \s-1LDAP\s0 entries represented in \s-1LDIF\s0
format files. Reading and writing are supported and may manipulate
single entries or lists of entries.
.PP
As when reading an entire file into memory with perl normally, take
into account the possibility of memory use when loading an \s-1LDIF\s0 file
in one go.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new ( \s-1FILE\s0 )" 4
.IX Item "new ( FILE )"
Open the file read-only. \f(CW\*(C`FILE\*(C'\fR may be the name of a file or an
already open filehandle. If \f(CW\*(C`FILE\*(C'\fR begins or ends with a \f(CW\*(C`|\*(C'\fR then
\&\f(CW\*(C`FILE\*(C'\fR will be passed directly to \f(CW\*(C`open\*(C'\fR.
.IP "new ( \s-1FILE\s0, \s-1MODE\s0, \s-1OPTIONS\s0 )" 4
.IX Item "new ( FILE, MODE, OPTIONS )"
Open the file with the given \f(CW\*(C`MODE\*(C'\fR, eg \*(L"w\*(R" or \*(L"a\*(R". \f(CW\*(C`FILE\*(C'\fR may be
the name of a file or an already open filehandle. If \f(CW\*(C`FILE\*(C'\fR begins or
ends with a \f(CW\*(C`|\*(C'\fR then \f(CW\*(C`FILE\*(C'\fR will be passed directly to \f(CW\*(C`open\*(C'\fR.
.RS 4
.IP "encode => 'none' | 'canonical' | 'base64'" 4
.IX Item "encode => 'none' | 'canonical' | 'base64'"
Some \s-1DN\s0 values in \s-1LDIF\s0 cannot be written verbatim and have to be encoded
in some way:
.RS 4
.IP "'none'" 4
.IX Item "'none'"
The default.
.IP "'canonical'" 4
.IX Item "'canonical'"
See \*(L"canonical_dn\*(R" in Net::LDAP::Util.
.IP "'base64'" 4
.IX Item "'base64'"
Use base64.
.RE
.RS 4
.RE
.IP "onerror => 'die' | 'warn' | undef" 4
.IX Item "onerror => 'die' | 'warn' | undef"
Specify what happens when an error is detected.
.RS 4
.IP "'die'" 4
.IX Item "'die'"
\&\f(CW\*(C`Net::LDAP::LDIF\*(C'\fR will croak with an appropriate message.
.IP "'warn'" 4
.IX Item "'warn'"
\&\f(CW\*(C`Net::LDAP::LDIF\*(C'\fR will warn with an appropriate message.
.IP "undef" 4
.IX Item "undef"
\&\f(CW\*(C`Net::LDAP::LDIF\*(C'\fR will warn with an appropriate message if \f(CW\*(C`\-w\*(C'\fR is
in effect.  The method that was called will return \f(CW\*(C`undef\*(C'\fR.
.RE
.RS 4
.RE
.IP "change => 1" 4
.IX Item "change => 1"
Write entry changes to the \s-1LDIF\s0 file instead of the entries itself.
I.e. write \s-1LDAP\s0 operations acting on the entries to the file instead of the entries contents.
.IP "lowercase => 1" 4
.IX Item "lowercase => 1"
Convert attribute names to lowercase when writing.
.IP "sort => 1" 4
.IX Item "sort => 1"
Sort attribute names when writing entries according to the rule:
objectclass first then all other attributes alphabetically sorted
.IP "version => '1'" 4
.IX Item "version => '1'"
Set the \s-1LDIF\s0 version to write to the resulting \s-1LDIF\s0 file.
.Sp
According to \s-1RFC\s0 2849 currently the only legal value for this option is \fI1\fR.
.Sp
When this option is set Net::LDAP::LDIF tries to adhere more strictly to the
\&\s-1LDIF\s0 specification in \s-1RFC2489\s0 in a few places.
.Sp
The default is \fIundef\fR meaning no version information is written to the \s-1LDIF\s0 file.
.IP "wrap => 78" 4
.IX Item "wrap => 78"
Number of columns where output line wrapping shall occur.
.Sp
Default is 78. Setting it to 40 or lower inhibits wrapping.
.IP "raw => \s-1REGEX\s0" 4
.IX Item "raw => REGEX"
Use \s-1REGEX\s0 to denote the names of attributes that are to be considered
binary in search results.
.Sp
When running on Perl 5.8 and this option is given Net::LDAP converts all
values of attributes not matching this \s-1REGEX\s0 into Perl \s-1UTF\-8\s0 strings
so that the regular Perl operators (pattern matching, ...) can operate
as one expects even on strings with international characters.
.Sp
If this option is not given or the version of Perl Net::LDAP is running on
is too old strings are encodeed the same as in earlier versions of perl-ldap.
.Sp
Example: raw => qr/(?i:^jpegPhoto|;binary)/
.RE
.RS 4
.RE
.SH "METHODS"
.IX Header "METHODS"
.IP "read_entry ( )" 4
.IX Item "read_entry ( )"
Read one entry from the file and return it as a \f(CW\*(C`Net::LDAP::Entry\*(C'\fR
object.
.IP "eof ( )" 4
.IX Item "eof ( )"
Returns \fItrue\fR when the end of the file is reached.
.IP "write_entry ( \s-1ENTRIES\s0 )" 4
.IX Item "write_entry ( ENTRIES )"
Write the entries to the \s-1LDIF\s0 file.
.IP "write_version ( )" 4
.IX Item "write_version ( )"
If the object's version is defined, this method allows one to explicitly
write the version before an entry is written.
.Sp
If  not called explicitly, it gets called automatically when writing
the first entry.
.IP "version ( [ \s-1VERSION\s0 ] )" 4
.IX Item "version ( [ VERSION ] )"
If called without arguments it returns the version of the \s-1LDIF\s0 file
or undef if no version has been set.
If called with an argument it sets the \s-1LDIF\s0 version to \s-1VERSION\s0.
.Sp
According to \s-1RFC\s0 2849 currently the only legal value for \s-1VERSION\s0 is \fI1\fR.
.IP "handle ( )" 4
.IX Item "handle ( )"
Returns the file handle the \f(CW\*(C`Net::LDAP::LDIF\*(C'\fR object reads from
or writes to.
.IP "done ( )" 4
.IX Item "done ( )"
This method signals that the \s-1LDIF\s0 object is no longer needed. If a
file was opened automatically when the object was created it will be
closed. This method is called automatically via \s-1DESTROY\s0 when the
object goes out of scope.
.IP "error ( )" 4
.IX Item "error ( )"
Returns error message if error was found.
.IP "error_lines ( )" 4
.IX Item "error_lines ( )"
Returns lines that resulted in error.
.IP "current_entry ( )" 4
.IX Item "current_entry ( )"
Returns the current \f(CW\*(C`Net::LDAP::Entry\*(C'\fR object.
.IP "current_lines ( )" 4
.IX Item "current_lines ( )"
Returns the lines that generated the current \f(CW\*(C`Net::LDAP::Entry\*(C'\fR
object.
.IP "next_lines ( )" 4
.IX Item "next_lines ( )"
Returns the lines that will generate the next \f(CW\*(C`Net::LDAP::Entry\*(C'\fR
object.
.SH "AUTHOR"
.IX Header "AUTHOR"
Graham Barr <gbarr@pobox.com>.
.PP
Please report any bugs, or post any suggestions, to the perl-ldap
mailing list <perl\-ldap@perl.org>.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1997\-2004 Graham Barr. All rights reserved. This program
is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.