1Net::LDAP::LDIF(3) User Contributed Perl Documentation Net::LDAP::LDIF(3)
2
6 Net::LDAP::LDIF - LDIF reading and writing
7
9 use Net::LDAP::LDIF;
10 $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
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 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
34 By default, Net::LDAP::LDIF supports reading attribute values from URLs
35 of type "file://".
36 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
43 new ( FILE [[, MODE ], OPTIONS ] )
44 Open the file with the given mode.
45 "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 "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 "OPTIONS" is a list of name/value pairs, recognizing:
58 encode => 'none' | 'canonical' | 'base64'
60 Some DN values in LDIF cannot be written verbatim and have to
61 be encoded in some way:
62 'none'
64 The default.
65 'canonical'
67 See "canonical_dn" in Net::LDAP::Util.
68 'base64'
70 Use base64.
71 onerror => 'die' | 'warn' | 'undef'
73 Specify what happens when an error is detected.
74 'die'
76 "Net::LDAP::LDIF" will croak with an appropriate message.
77 'warn'
79 "Net::LDAP::LDIF" will warn with an appropriate message.
80 '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 Note this value is the string 'undef', not the "undef"
87 value.
88 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 lowercase => 1
95 Convert attribute names to lowercase when writing.
96 sort => 1
98 Sort attribute names when writing entries according to the
99 rule: objectclass first then all other attributes
100 alphabetically sorted
101 version => '1'
103 Set the LDIF version to write to the resulting LDIF file.
104 According to RFC 2849 currently the only legal value for this
106 option is 1.
107 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 The default is undef meaning no version information is written
112 to the LDIF file.
113 wrap => 78
115 Number of columns where output line wrapping shall occur.
116 Default is 78. Setting it to 40 or lower inhibits wrapping.
118 raw => REGEX
120 Use REGEX to denote the names of attributes that are to be
121 considered binary when reading.
122 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 If this option is not given, attribute values are treated as
130 byte strings.
131 Example: raw => qr/(?i:^jpegPhoto|;binary)/
133
135 read_entry ( )
136 Read one entry from the file and return it as a "Net::LDAP::Entry"
137 object.
138 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 eof ( )
146 Returns true when the end of the file is reached.
147 write_entry ( ENTRY [, OPTIONS ], ... )
149 Write entries to the LDIF file.
150 The arguments accepted are a list of entries, optionally
152 interspersed with options belonging to the preceding entry.
153 For each entry, "OPTIONS" is a list of key-value pairs,
155 recognizing:
156 control => CONTROL
158 control => [ CONTROL, ... ]
159 See "CONTROLS" in Net::LDAP.
160 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 If not called explicitly, it gets called automatically when
166 writing the first entry.
167 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 According to RFC 2849 currently the only legal value for VERSION is
174 1.
175 handle ( )
177 Returns the file handle the "Net::LDAP::LDIF" object reads from or
178 writes to.
179 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 error ( )
187 Returns error message if error was found.
188 error_lines ( )
190 Returns lines that resulted in error.
191 current_entry ( )
193 Returns the current "Net::LDAP::Entry" object.
194 current_lines ( )
196 Returns the lines that generated the current "Net::LDAP::Entry"
197 object.
198 next_lines ( )
200 Returns the lines that will generate the next "Net::LDAP::Entry"
201 object.
202
204 Graham Barr <gbarr@pobox.com>.
205 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.
213perl v5.32.1 2021-02-16 Net::LDAP::LDIF(3)