1Net::LDAP::LDIF(3)    User Contributed Perl Documentation   Net::LDAP::LDIF(3)
2
3
4

NAME

6       Net::LDAP::LDIF - LDIF reading and writing
7

SYNOPSIS

9        use Net::LDAP::LDIF;
10
11        $ldif = Net::LDAP::LDIF->new( "file.ldif", "r", onerror => 'undef' );
12        while ( not $ldif->eof ( ) ) {
13          $entry = $ldif->read_entry ( );
14          if ( $ldif->error ( ) ) {
15            print "Error msg: ", $ldif->error ( ), "\n";
16            print "Error lines:\n", $ldif->error_lines ( ), "\n";
17          } else {
18            # do stuff
19          }
20        }
21        $ldif->done ( );
22

DESCRIPTION

24       Net::LDAP::LDIF provides a means to convert between Net::LDAP::Entry
25       objects and LDAP entries represented in LDIF format files. Reading and
26       writing are supported and may manipulate single entries or lists of
27       entries.
28
29       As when reading an entire file into memory with perl normally, take
30       into account the possibility of memory use when loading an LDIF file in
31       one go.
32

SPECIAL FEATURES

34       By default, Net::LDAP::LDIF supports reading attribute values from URLs
35       of type "file://".
36
37       When Gisle Aas' LWP module package is installed, Net::LDAP::LDIF uses
38       it to also support reading data from the URL types supported by these
39       modules; most prominently "http://", "https://", and "ftp://"
40       resources.  This extended feature is dynamically detected at runtime.
41

CONSTRUCTOR

43       new ( FILE [[, MODE ], OPTIONS ] )
44           Open the file with the given mode.
45
46           "FILE" may be the name of a file or an already open filehandle. If
47           "FILE" begins or ends with a "|" then "FILE" will be passed
48           directly to "open".
49
50           "MODE" can be any of the modes allowed for Perl's open() function,
51           potentially extended by PerlIO layers as described in perlopentut.
52           Alternatively, it can be one of the mode indicators "r", "r+", "w",
53           "w+", "a", "a+" known from C's fopen() function, which get mapped
54           to their Perl counterparts.  If "MODE" is omitted, it defaults to
55           "r" for reading.
56
57           "OPTIONS" is a list of name/value pairs, recognizing:
58
59           encode => 'none' | 'canonical' | 'base64'
60               Some DN values in LDIF cannot be written verbatim and have to
61               be encoded in some way:
62
63               'none'
64                   The default.
65
66               'canonical'
67                   See "canonical_dn" in Net::LDAP::Util.
68
69               'base64'
70                   Use base64.
71
72           onerror => 'die' | 'warn' | 'undef'
73               Specify what happens when an error is detected.
74
75               'die'
76                   "Net::LDAP::LDIF" will croak with an appropriate message.
77
78               'warn'
79                   "Net::LDAP::LDIF" will warn with an appropriate message.
80
81               'undef'
82                   "Net::LDAP::LDIF" will warn with an appropriate message if
83                   "-w" is in effect.  The method that was called will return
84                   "undef".
85
86                   Note this value is the string 'undef', not the "undef"
87                   value.
88
89           change => 1
90               Write entry changes to the LDIF file instead of the entries
91               itself.  I.e. write LDAP operations acting on the entries to
92               the file instead of the entries contents.
93
94           lowercase => 1
95               Convert attribute names to lowercase when writing.
96
97           sort => 1
98               Sort attribute names when writing entries according to the
99               rule: objectclass first then all other attributes
100               alphabetically sorted
101
102           version => '1'
103               Set the LDIF version to write to the resulting LDIF file.
104
105               According to RFC 2849 currently the only legal value for this
106               option is 1.
107
108               When this option is set Net::LDAP::LDIF tries to adhere more
109               strictly to the LDIF specification in RFC2489 in a few places.
110
111               The default is undef meaning no version information is written
112               to the LDIF file.
113
114           wrap => 78
115               Number of columns where output line wrapping shall occur.
116
117               Default is 78. Setting it to 40 or lower inhibits wrapping.
118
119           raw => REGEX
120               Use REGEX to denote the names of attributes that are to be
121               considered binary when reading.
122
123               When this option is given, Net::LDAP converts all values of
124               attributes not matching this REGEX into Perl UTF-8 strings so
125               that the regular Perl operators (pattern matching, ...) can
126               operate as one expects even on strings with international
127               characters.
128
129               If this option is not given, attribute values are treated as
130               byte strings.
131
132               Example: raw => qr/(?i:^jpegPhoto|;binary)/
133

METHODS

135       read_entry ( )
136           Read one entry from the file and return it as a "Net::LDAP::Entry"
137           object.
138
139           In scalar mode, the "Net::LDAP::Entry" object is returned alone,
140           while in list mode a list is returned consisting of the
141           "Net::LDAP::Entry" object as first element followed by  all
142           "Net::LDAP::Control" objects that were part of the LDIF entry.  See
143           RFC 2849 for details.
144
145       eof ( )
146           Returns true when the end of the file is reached.
147
148       write_entry ( ENTRY [, OPTIONS ], ... )
149           Write entries to the LDIF file.
150
151           The arguments accepted are a list of entries, optionally
152           interspersed with options belonging to the preceding entry.
153
154           For each entry, "OPTIONS" is a list of key-value pairs,
155           recognizing:
156
157           control => CONTROL
158           control => [ CONTROL, ... ]
159               See "CONTROLS" in Net::LDAP.
160
161       write_version ( )
162           If the object's version is defined, this method allows one to
163           explicitly write the version before an entry is written.
164
165           If  not called explicitly, it gets called automatically when
166           writing the first entry.
167
168       version ( [ VERSION ] )
169           If called without arguments it returns the version of the LDIF file
170           or undef if no version has been set.  If called with an argument it
171           sets the LDIF version to VERSION.
172
173           According to RFC 2849 currently the only legal value for VERSION is
174           1.
175
176       handle ( )
177           Returns the file handle the "Net::LDAP::LDIF" object reads from or
178           writes to.
179
180       done ( )
181           This method signals that the LDIF object is no longer needed. If a
182           file was opened automatically when the object was created it will
183           be closed. This method is called automatically via DESTROY when the
184           object goes out of scope.
185
186       error ( )
187           Returns error message if error was found.
188
189       error_lines ( )
190           Returns lines that resulted in error.
191
192       current_entry ( )
193           Returns the current "Net::LDAP::Entry" object.
194
195       current_lines ( )
196           Returns the lines that generated the current "Net::LDAP::Entry"
197           object.
198
199       next_lines ( )
200           Returns the lines that will generate the next "Net::LDAP::Entry"
201           object.
202

AUTHOR

204       Graham Barr <gbarr@pobox.com>.
205
206       Please report any bugs, or post any suggestions, to the perl-ldap
207       mailing list <perl-ldap@perl.org>.
208
210       Copyright (c) 1997-2004 Graham Barr. All rights reserved. This program
211       is free software; you can redistribute it and/or modify it under the
212       same terms as Perl itself.
213
214
215
216perl v5.34.0                      2022-01-21                Net::LDAP::LDIF(3)
Impressum