.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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::Entry 3"
.TH Net::LDAP::Entry 3 "2015-04-02" "perl v5.16.3" "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::Entry \- An LDAP entry object
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Net::LDAP;
\&
\& $ldap = Net::LDAP\->new ( $host );
\& $mesg = $ldap\->search ( @search_args );
\&
\& my $max = $mesg\->count;
\& for ( $i = 0 ; $i < $max ; $i++ ) {
\&   my $entry = $mesg\->entry ( $i );
\&   foreach my $attr ( $entry\->attributes ) {
\&     print join( "\en ", $attr, $entry\->get_value( $attr ) ), "\en";
\&   }
\& }
\&
\& # or
\&
\& use Net::LDAP::Entry;
\&
\& $entry = Net::LDAP::Entry\->new;
\&
\& $entry\->dn($dn);
\&
\& $entry\->add (
\&   attr1 => \*(Aqvalue1\*(Aq,
\&   attr2 => [ qw(value1 value2) ]
\& );
\&
\& $entry\->delete ( \*(Aqunwanted\*(Aq );
\&
\& $entry\->replace (
\&   attr1 => \*(Aqnewvalue\*(Aq
\&   attr2 => [ qw(new values) ]
\& );
\&
\& $entry\->update ( $ldap ); # update directory server
\&
\& $entry2 = $entry\->clone; # copies entry
\&
\& # new alternate syntax
\&
\& $entry = Net::LDAP::Entry\->new ( $dn
\&   , attr1 => \*(Aqvalue1\*(Aq
\&   , attr2 => [ qw(value1 value2) ]
\& )\->add(
\&   attr3   => \*(Aqvalue\*(Aq
\& )\->update( $ldap );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBNet::LDAP::Entry\fR object represents a single entry in the
directory.  It is a container for attribute-value pairs.
.PP
A \fBNet::LDAP::Entry\fR object can be used in two situations. The first
and probably most common use is in the result of a search to the
directory server.
.PP
The other is where a new object is created locally and then a single
command is sent to the directory server to add, modify or replace an
entry. Entries for this purpose can also be created by reading an \s-1LDIF\s0
file with the Net::LDAP::LDIF module.
.SH "CONSTRUCTORS"
.IX Header "CONSTRUCTORS"
.IP "new ( )" 4
.IX Item "new ( )"
Create a new entry object with the changetype set to \f(CW\*(Aqadd\*(Aq\fR.
Optionally, you can provide a \s-1DN\s0 and a list of arguments passed to the
add method.
.Sp
.Vb 1
\& Net::LDAP::Entry\->new()
\&
\& # or
\& Net::LDAP::Entry\->new( $dn )
\&
\& # or
\& Net::LDAP::Entry\->new( $dn ,
\&  objectClass => [qw( top posixAccount )] , uid => \*(Aqadmin\*(Aq
\& )
.Ve
.IP "clone ( )" 4
.IX Item "clone ( )"
Returns a copy of the \fBNet::LDAP::Entry\fR object.
.SH "METHODS"
.IX Header "METHODS"
.IP "add ( \s-1ATTR\s0 => \s-1VALUE, ... \s0)" 4
.IX Item "add ( ATTR => VALUE, ... )"
Add more attributes or values to the entry and returns the entry itself. Each
\&\f(CW\*(C`VALUE\*(C'\fR should be a string if only a single value is wanted in the attribute,
or a reference to an array of strings if multiple values are wanted. The values
given will be added to the values which already exist for the given attributes.
.Sp
.Vb 1
\& $entry\->add ( \*(Aqsn\*(Aq => \*(AqBarr\*(Aq );
\&
\& $entry\->add ( \*(Aqstreet\*(Aq => [ \*(Aq1 some road\*(Aq,\*(Aqnowhere\*(Aq ] );
.Ve
.Sp
\&\fB\s-1NOTE\s0\fR: these changes are local to the client and will not appear on
the directory server until the \f(CW\*(C`update\*(C'\fR method is called. As \f(CW\*(C`add\*(C'\fR returns the
entry, you can write something like.
.Sp
.Vb 1
\& $entry\->add ( \*(Aqsn\*(Aq => \*(AqBarr\*(Aq )\->update( $ldap );
.Ve
.IP "attributes ( \s-1OPTIONS \s0)" 4
.IX Item "attributes ( OPTIONS )"
Return a list of attributes in this entry
.RS 4
.IP "nooptions => 1" 4
.IX Item "nooptions => 1"
Return a list of the attribute names excluding any options. For
example for the entry
.Sp
.Vb 3
\&  name: Graham Barr
\&  name;en\-us: Bob
\&  jpeg;binary: **binary data**
.Ve
.Sp
then
.Sp
.Vb 2
\&  @values = $entry\->attributes;
\&  print "default: @values\en";
\&
\&  @values = $entry\->attributes ( nooptions => 1 );
\&  print "nooptions: @values\en";
.Ve
.Sp
will output
.Sp
.Vb 2
\&  default: name name;en\-us jpeg;binary
\&  nooptions: name jpeg
.Ve
.RE
.RS 4
.RE
.IP "changetype ( )" 4
.IX Item "changetype ( )"
Returns the type of operation that would be performed when the update
method is called.
.IP "changetype ( \s-1TYPE \s0)" 4
.IX Item "changetype ( TYPE )"
Set the type of operation that will be performed when the update
method is called to \f(CW\*(C`TYPE\*(C'\fR. Returns the entry itself.
.Sp
Possible values for \f(CW\*(C`TYPE\*(C'\fR are
.RS 4
.IP "add" 4
.IX Item "add"
The update method will call the add method on the client object, which
will result in the entry being added to the directory server.
.IP "delete" 4
.IX Item "delete"
The update method will call the delete method on the client object,
which will result in the entry being removed from the directory
server.
.Sp
.Vb 1
\& $entry\->delete\->update( $ldap )
.Ve
.IP "modify" 4
.IX Item "modify"
The update method will call the modify method on the client object,
which will result in any changes that have been made locally being
made to the entry on the directory server.
.IP "moddn/modrdn" 4
.IX Item "moddn/modrdn"
The update method will call the moddn method on the client object,
which will result in any \s-1DN\s0 changes that have been made locally being
made to the entry on the directory server. These \s-1DN\s0 changes are
specified by setting the entry attributes newrdn, deleteoldrdn, and
(optionally) newsuperior.
.RE
.RS 4
.RE
.IP "delete ( )" 4
.IX Item "delete ( )"
Delete the entry from the server on the next call to \f(CW\*(C`update\*(C'\fR.
.IP "delete ( \s-1ATTR\s0 => [ \s-1VALUE, ... \s0], ... )" 4
.IX Item "delete ( ATTR => [ VALUE, ... ], ... )"
Delete the values of given attributes from the entry. Values are
references to arrays; passing a reference to an empty array is the
same as passing \f(CW\*(C`undef\*(C'\fR, and will result in the entire attribute
being deleted. For example:
.Sp
.Vb 2
\& $entry\->delete ( \*(Aqmail\*(Aq => [ \*(Aqfoo.bar@example.com\*(Aq ] );
\& $entry\->delete ( \*(Aqdescription\*(Aq => [ ], \*(AqstreetAddress\*(Aq => [ ] );
.Ve
.Sp
\&\fB\s-1NOTE\s0\fR: these changes are local to the client and will not appear on
the directory server until the \f(CW\*(C`update\*(C'\fR method is called.
.IP "dn ( )" 4
.IX Item "dn ( )"
Get the \s-1DN\s0 of the entry.
.IP "dn ( \s-1DN \s0)" 4
.IX Item "dn ( DN )"
Set the \s-1DN\s0 for the entry, and return the previous value.
.Sp
\&\fB\s-1NOTE\s0\fR: these changes are local to the client and will not appear on
the directory server until the \f(CW\*(C`update\*(C'\fR method is called.
.IP "ldif ( \s-1OPTION\s0 => \s-1VALUE, ... \s0)" 4
.IX Item "ldif ( OPTION => VALUE, ... )"
Returns the entry as an \s-1LDIF\s0 string. Possible options are
.RS 4
.IP "change => \s-1VALUE\s0" 4
.IX Item "change => VALUE"
If given a true value then the \s-1LDIF\s0 will be generated as a change record.
If false, then the \s-1LDIF\s0 generated will represent the entry content. If
unspecified then it will default to true if the entry has changes and
false if no changes have been applied to the entry.
.RE
.RS 4
.RE
.IP "dump ( [ \s-1FILEHANDLE \s0] )" 4
.IX Item "dump ( [ FILEHANDLE ] )"
Dump the entry to the given filehandle.
.Sp
This method is intended for debugging purposes and does not
treat binary attributes specially.
.Sp
See Net::LDAP::LDIF on how to generate \s-1LDIF\s0 output.
.Sp
If \f(CW\*(C`FILEHANDLE\*(C'\fR is omitted \f(CW\*(C`STDOUT\*(C'\fR is used by default.
.IP "exists ( \s-1ATTR \s0)" 4
.IX Item "exists ( ATTR )"
Returns \f(CW\*(C`TRUE\*(C'\fR if the entry has an attribute called \f(CW\*(C`ATTR\*(C'\fR.
.IP "get_value ( \s-1ATTR, OPTIONS \s0)" 4
.IX Item "get_value ( ATTR, OPTIONS )"
Get the values for the attribute \f(CW\*(C`ATTR\*(C'\fR. In a list context returns
all values for the given attribute, or the empty list if the attribute
does not exist. In a scalar context returns the first value for the
attribute or undef if the attribute does not exist.
.RS 4
.IP "alloptions => 1" 4
.IX Item "alloptions => 1"
The result will be a hash reference. The keys of the hash will be the
options and the hash value will be the values for those attributes.
For example if an entry had:
.Sp
.Vb 2
\& name: Graham Barr
\& name;en\-us: Bob
.Ve
.Sp
Then a get for attribute \*(L"name\*(R" with alloptions set to a true value
.Sp
.Vb 1
\& $ref = $entry\->get_value ( \*(Aqname\*(Aq, alloptions => 1 );
.Ve
.Sp
will return a hash reference that would be like
.Sp
.Vb 4
\& {
\&   \*(Aq\*(Aq       => [ \*(AqGraham Barr\*(Aq ],
\&   \*(Aq;en\-us\*(Aq => [ \*(AqBob\*(Aq ]
\& }
.Ve
.Sp
If alloptions is not set or is set to false only the attribute values
for the exactly matching name are returned.
.IP "asref => 1" 4
.IX Item "asref => 1"
The result will be a reference to an array containing all the values
for the attribute, or \f(CW\*(C`undef\*(C'\fR if the attribute does not exist.
.Sp
.Vb 1
\& $scalar = $entry\->get_value ( \*(Aqname\*(Aq );
.Ve
.Sp
\&\f(CW$scalar\fR will be the first value for the \f(CW\*(C`name\*(C'\fR attribute, or \f(CW\*(C`undef\*(C'\fR
if the entry does not contain a \f(CW\*(C`name\*(C'\fR attribute.
.Sp
.Vb 1
\& $ref = $entry\->get_value ( \*(Aqname\*(Aq, asref => 1 );
.Ve
.Sp
\&\f(CW$ref\fR will be a reference to an array, which will have all the values
for the \f(CW\*(C`name\*(C'\fR attribute. If the entry does not have an attribute
called \f(CW\*(C`name\*(C'\fR then \f(CW$ref\fR will be \f(CW\*(C`undef\*(C'\fR.
.RE
.RS 4
.Sp
\&\fB\s-1NOTE\s0\fR: In the interest of performance the array references returned
by \f(CW\*(C`get_value\*(C'\fR are references to structures held inside the entry
object. These values and their contents should \fB\s-1NOT\s0\fR be modified
directly.
.RE
.IP "replace ( \s-1ATTR\s0 => \s-1VALUE, ... \s0)" 4
.IX Item "replace ( ATTR => VALUE, ... )"
Similar to \f(CW\*(C`add\*(C'\fR, except that the values given will replace any
values that already exist for the given attributes.
.Sp
\&\fB\s-1NOTE\s0\fR: these changes are local to the client and will not appear on
the directory server until the \f(CW\*(C`update\*(C'\fR method is called.
.IP "update ( \s-1CLIENT\s0 [, \s-1OPTIONS \s0] )" 4
.IX Item "update ( CLIENT [, OPTIONS ] )"
Update the directory server with any changes that have been made
locally to the attributes of this entry. This means any calls that
have been made to add, replace or delete since the last call to
changetype or update was made.
.Sp
This method can also be used to modify the \s-1DN\s0 of the entry on the
server, by specifying moddn or modrdn as the changetype, and setting
the entry attributes newrdn, deleteoldrdn, and (optionally)
newsuperior.
.Sp
\&\f(CW\*(C`CLIENT\*(C'\fR is a \f(CW\*(C`Net::LDAP\*(C'\fR object where the update will be sent to.
.Sp
\&\f(CW\*(C`OPTIONS\*(C'\fR may be options to the \f(CW\*(C`Net::LDAP\*(C'\fR actions on \s-1CLIENT\s0
corresponding to the entry's changetype.
.Sp
The result will be an object of type Net::LDAP::Message as returned
by the add, modify or delete method called on \s-1CLIENT.\s0
.Sp
Alternatively \f(CW\*(C`CLIENT\*(C'\fR can also be a \f(CW\*(C`Net::LDAP::LDIF\*(C'\fR object, that
must be an \s-1LDIF\s0 file opened for writing.
.Sp
In this case, the entry, together with any \f(CW\*(C`OPTIONS\*(C'\fR is passed as
arguments to the \f(CW\*(C`write_entry\*(C'\fR method of the \f(CW\*(C`CLIENT\*(C'\fR object.
.Sp
Here too, the result is an object class \f(CW\*(C`Net::LDAP::Message\*(C'\fR.
On error, the error code is \f(CW\*(C`LDAP_OTHER\*(C'\fR with the \s-1LDIF\s0 error message
in the error text.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::LDAP,
Net::LDAP::LDIF
.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.