.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "SmbClient 3pm"
.TH SmbClient 3pm "2020-11-09" "perl v5.32.0" "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"
Filesys::SmbClient \- Interface for access Samba filesystem with libsmclient.so
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use POSIX;
\&  use Filesys::SmbClient;
\&  
\&  my $smb = new Filesys::SmbClient(username  => "alian",
\&                                   password  => "speed",
\&                                   workgroup => "alian",
\&                                   debug     => 10);
\&  
\&  # Read a file
\&  my $fd = $smb\->open("smb://jupiter/doc/general.css", \*(Aq0666\*(Aq);
\&  while (defined(my $l= $smb\->read($fd,50))) {print $l; }
\&  $smb\->close(fd);
\&  
\&  # ...
.Ve
.PP
See section \s-1EXAMPLE\s0 for others scripts.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provide interface to access routine defined in libsmbclient.so provided with
Samba.
.PP
Since 3.0 release of this package, you need a least samba\-3.0.2.
For prior release of Samba, use Filesys::SmbClient version 1.x.
.PP
For old and 2.x release, this library is available on Samba source, but is not
build by default.
Do \*(L"make bin/libsmbclient.so\*(R" in sources directory of Samba to build 
this libraries. Then copy source/include/libsmbclient.h to
/usr/local/samba/include and source/bin/libsmbclient.so to
/usr/local/samba/lib before install this module.
.PP
If you want to use filehandle with this module, you need Perl 5.6 or later.
.PP
When a path is used, his scheme is :
.PP
.Vb 1
\&  smb://server/share/rep/doc
.Ve
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW$Revision:\fR 3.2 $
.SH "FONCTIONS"
.IX Header "FONCTIONS"
.ie n .IP "new %hash" 4
.el .IP "new \f(CW%hash\fR" 4
.IX Item "new %hash"
Init connection
Hash can have this keys:
.RS 4
.IP "\(bu" 4
username
.IP "\(bu" 4
password
.IP "\(bu" 4
workgroup
.IP "\(bu" 4
debug
.IP "\(bu" 4
flags : See set_flag
.RE
.RS 4
.Sp
Return instance of Filesys::SmbClient on succes, die with error else.
.Sp
Example:
.Sp
.Vb 4
\&  my $smb = new Filesys::SmbClient(username  => "alian",
\&                                   password  => "speed", 
\&                                   workgroup => "alian",
\&                                   debug     => 10);
.Ve
.RE
.IP "set_flag" 4
.IX Item "set_flag"
Set flag for smb connection. See _SMBCCTX\->flags in libsmclient.h
Flag can be:
.RS 4
.IP "\s-1SMB_CTX_FLAG_USE_KERBEROS\s0" 4
.IX Item "SMB_CTX_FLAG_USE_KERBEROS"
.PD 0
.IP "\s-1SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS\s0" 4
.IX Item "SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS"
.IP "\s-1SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON\s0" 4
.IX Item "SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON"
.RE
.RS 4
.RE
.PD
.SS "Tie Filesys::SmbClient filehandle"
.IX Subsection "Tie Filesys::SmbClient filehandle"
This didn't work before 5.005_64. Why, I don't know.
When you have tied a filehandle with Filesys::SmbClient,
you can call classic methods for filehandle:
print, printf, seek, syswrite, getc, open, close, read.
See perldoc for usage.
.PP
Example:
.PP
.Vb 6
\&  local *FD;
\&  tie(*FD, \*(AqFilesys::SmbClient\*(Aq);
\&  open(FD,"smb://jupiter/doc/test")
\&    or print "Can\*(Aqt open file:", $!, "\en";
\&  while(<FD>) { print $_; }
\&  close(FD);
.Ve
.PP
or
.PP
.Vb 7
\&  local *FD;
\&  tie(*FD, \*(AqFilesys::SmbClient\*(Aq);
\&  open(FD,">smb://jupiter/doc/test")
\&    or print "Can\*(Aqt create file:", $!, "\en";
\&  print FD "Samba test","\en";
\&  printf FD "%s", "And that work !\en";
\&  close(FD);
.Ve
.SS "Directory"
.IX Subsection "Directory"
.IP "mkdir \s-1FILENAME, MODE\s0" 4
.IX Item "mkdir FILENAME, MODE"
Create directory \f(CW$fname\fR with permissions set to \f(CW$mode\fR.
Return 1 on success, else 0 is return and errno and $! is set.
.Sp
Example:
.Sp
.Vb 2
\&  $smb\->mkdir("smb://jupiter/doc/toto",\*(Aq0666\*(Aq) 
\&    or print "Error mkdir: ", $!, "\en";
.Ve
.IP "rmdir \s-1FILENAME\s0" 4
.IX Item "rmdir FILENAME"
Erase directory \f(CW$fname\fR. Return 1 on success, else 0 is return
and errno and $! is set. ($fname must be empty, else see 
rmdir_recurse).
.Sp
Example:
.Sp
.Vb 2
\&  $smb\->rmdir("smb://jupiter/doc/toto")
\&    or print "Error rmdir: ", $!, "\en";
.Ve
.IP "rmdir_recurse \s-1FILENAME\s0" 4
.IX Item "rmdir_recurse FILENAME"
Erase directory \f(CW$fname\fR. Return 1 on success, else 0 is return
and errno and $! is set. Il \f(CW$fname\fR is not empty, all files and
dir will be deleted.
.Sp
Example:
.Sp
.Vb 2
\&  $smb\->rmdir_recurse("smb://jupiter/doc/toto")
\&    or print "Error rmdir_recurse: ", $!, "\en";
.Ve
.IP "opendir \s-1FILENAME\s0" 4
.IX Item "opendir FILENAME"
Open directory \f(CW$fname\fR. Return file descriptor on succes, else 0 is
return and $! is set.
.IP "readdir \s-1FILEHANDLE\s0" 4
.IX Item "readdir FILEHANDLE"
Read a directory. In a list context, return the full content of
the directory \f(CW$fd\fR, else return next element. Each elem is
a name of a directory or files.
.Sp
Return undef at end of directory.
.Sp
Example:
.Sp
.Vb 3
\&  my $fd = $smb\->opendir("smb://jupiter/doc");
\&  foreach my $n ($smb\->readdir($fd)) {print $n,"\en";}
\&  close($fd);
.Ve
.IP "readdir_struct \s-1FILEHANDLE\s0" 4
.IX Item "readdir_struct FILEHANDLE"
Read a directory. In a list context, return the full content of
the directory \s-1FILEHANDLE,\s0 else return next element. Each element
is a ref to an array with type, name and comment. Type can be :
.RS 4
.IP "\s-1SMBC_WORKGROUP\s0" 4
.IX Item "SMBC_WORKGROUP"
.PD 0
.IP "\s-1SMBC_SERVER\s0" 4
.IX Item "SMBC_SERVER"
.IP "\s-1SMBC_FILE_SHARE\s0" 4
.IX Item "SMBC_FILE_SHARE"
.IP "\s-1SMBC_PRINTER_SHARE\s0" 4
.IX Item "SMBC_PRINTER_SHARE"
.IP "\s-1SMBC_COMMS_SHARE\s0" 4
.IX Item "SMBC_COMMS_SHARE"
.IP "\s-1SMBC_IPC_SHARE\s0" 4
.IX Item "SMBC_IPC_SHARE"
.IP "\s-1SMBC_DIR\s0" 4
.IX Item "SMBC_DIR"
.IP "\s-1SMBC_FILE\s0" 4
.IX Item "SMBC_FILE"
.IP "\s-1SMBC_LINK\s0" 4
.IX Item "SMBC_LINK"
.RE
.RS 4
.PD
.Sp
Return undef at end of directory.
.Sp
Example:
.Sp
.Vb 7
\&  my $fd = $smb\->opendir("smb://jupiter/doc");
\&  while (my $f = $smb\->readdir_struct($fd)) {
\&    if ($f\->[0] == SMBC_DIR) {print "Directory ",$f\->[1],"\en";}
\&    elsif ($f\->[0] == SMBC_FILE) {print "File ",$f\->[1],"\en";}
\&    # ...
\&  }
\&  close($fd);
.Ve
.RE
.IP "closedir \s-1FILEHANDLE\s0" 4
.IX Item "closedir FILEHANDLE"
Close directory \f(CW$fd\fR.
.SS "Files"
.IX Subsection "Files"
.IP "stat \s-1FILENAME\s0" 4
.IX Item "stat FILENAME"
Stat a file \s-1FILENAME.\s0 Return a list with info on success,
else an empty list is return and $! is set.
.Sp
List is made with:
.RS 4
.IP "\(bu" 4
device
.IP "\(bu" 4
inode
.IP "\(bu" 4
protection
.IP "\(bu" 4
number of hard links
.IP "\(bu" 4
user \s-1ID\s0 of owner
.IP "\(bu" 4
group \s-1ID\s0 of owner
.IP "\(bu" 4
device type (if inode device)
.IP "\(bu" 4
total size, in bytes
.IP "\(bu" 4
blocksize for filesystem I/O
.IP "\(bu" 4
number of blocks allocated
.IP "\(bu" 4
time of last access
.IP "\(bu" 4
time of last modification
.IP "\(bu" 4
time of last change
.RE
.RS 4
.Sp
Example:
.Sp
.Vb 6
\&  my @tab = $smb\->stat("smb://jupiter/doc/tata");
\&  if ($#tab == 0) { print "Erreur in stat:", $!, "\en"; }
\&  else {
\&    for (10..12) {$tab[$_] = localtime($tab[$_]);}
\&    print join("\en",@tab);
\&  }
.Ve
.RE
.IP "fstat \s-1FILEHANDLE\s0" 4
.IX Item "fstat FILEHANDLE"
Like stat, but on a file handle
.IP "rename \s-1OLDNAME,NEWNAME\s0" 4
.IX Item "rename OLDNAME,NEWNAME"
Changes the name of a file; an existing file \s-1NEWNAME\s0 will be clobbered.
Returns true for success, false otherwise, with $! set.
.Sp
Example:
.Sp
.Vb 2
\&  $smb\->rename("smb://jupiter/doc/toto","smb://jupiter/doc/tata")
\&    or print "Can\*(Aqt rename file:", $!, "\en";
.Ve
.IP "unlink \s-1FILENAME\s0" 4
.IX Item "unlink FILENAME"
Unlink \s-1FILENAME.\s0 Return 1 on success, else 0 is return
and errno and $! is set.
.Sp
Example:
.Sp
.Vb 2
\&  $smb\->unlink("smb://jupiter/doc/test") 
\&    or print "Can\*(Aqt unlink file:", $!, "\en";
.Ve
.IP "open \s-1FILENAME\s0" 4
.IX Item "open FILENAME"
.PD 0
.IP "open \s-1FILENAME, MODE\s0" 4
.IX Item "open FILENAME, MODE"
.PD
Open file \f(CW$fname\fR with perm \f(CW$mode\fR. Return file descriptor
on success, else 0 is return and $! is set.
.Sp
Example:
.Sp
.Vb 2
\&  my $fd = $smb\->open("smb://jupiter/doc/test", 0666) 
\&    or print "Can\*(Aqt read file:", $!, "\en";
\&  
\&  my $fd = $smb\->open(">smb://jupiter/doc/test", 0666) 
\&    or print "Can\*(Aqt create file:", $!, "\en";
\&  
\&  my $fd = $smb\->open(">>smb://jupiter/doc/test", 0666) 
\&    or print "Can\*(Aqt append to file:", $!, "\en";
.Ve
.IP "read \s-1FILEHANDLE\s0" 4
.IX Item "read FILEHANDLE"
.PD 0
.IP "read \s-1FILEHANDLE, LENGTH\s0" 4
.IX Item "read FILEHANDLE, LENGTH"
.PD
Read \f(CW$count\fR bytes of data on file descriptor \f(CW$fd\fR. It length is not set,
4096 bytes will be read.
.Sp
Return buffer read on success, undef at end of file,
\&\-1 is return on error and $! is set.
.Sp
\&\s-1FILEHANDLE\s0 must be open with open of this module.
.ie n .IP "write \s-1FILEHANDLE,\s0 $buf" 4
.el .IP "write \s-1FILEHANDLE,\s0 \f(CW$buf\fR" 4
.IX Item "write FILEHANDLE, $buf"
.PD 0
.ie n .IP "write \s-1FILEHANDLE,\s0 @buf" 4
.el .IP "write \s-1FILEHANDLE,\s0 \f(CW@buf\fR" 4
.IX Item "write FILEHANDLE, @buf"
.PD
Write \f(CW$buf\fR or \f(CW@buf\fR on file descriptor \f(CW$fd\fR.
Return number of bytes wrote, else \-1 is return and errno and $! is set.
.Sp
Example:
.Sp
.Vb 5
\&  my $fd = $smb\->open(">smb://jupiter/doc/test", 0666) 
\&    or print "Can\*(Aqt create file:", $!, "\en";
\&  $smb\->write($fd, "A test of write call") 
\&    or print $!,"\en";
\&  $smb\->close($fd);
.Ve
.Sp
\&\s-1FILEHANDLE\s0 must be open with open of this module.
.IP "seek \s-1FILEHANDLE, POS\s0" 4
.IX Item "seek FILEHANDLE, POS"
Sets \s-1FILEHANDLE\s0's position, just like the \*(L"fseek\*(R"
call of \*(L"stdio\*(R".  \s-1FILEHANDLE\s0 may be an expression
whose value gives the name of the filehandle.  The
values for \s-1WHENCE\s0 is always \s-1SEEK_SET\s0 because others
didn't work on libsmbclient.so
.Sp
\&\s-1FILEHANDLE\s0 must be open with open of this module.
.IP "close \s-1FILEHANDLE\s0" 4
.IX Item "close FILEHANDLE"
Close file \s-1FILEHANDLE.\s0 Return 0 on success, else \-1 is return and
errno and $! is set.
.IP "shutdown flag" 4
.IX Item "shutdown flag"
A wrapper around `libsmbclient's `smbc_free_context'.
.Sp
Close open files, release Samba connection, delete context,
acquired during open_* calls.
.Sp
Example:
.Sp
.Vb 2
\&    $smb\->shutdown(0); # Gracefully close connection
\&    $sbm\->shutdown(1); # Forcibly close files and connection
.Ve
.Sp
\&\s-1NOTE:\s0
    \fBshutdown\fR\|(1) may cause complaints about talloc memory
    leaks, if there are currently no open files.
.SS "Print method"
.IX Subsection "Print method"
.IP "unlink_print_job \s-1PRINTER_URL, IDJOB\s0" 4
.IX Item "unlink_print_job PRINTER_URL, IDJOB"
Remove job number \s-1IDJOB\s0 on printer \s-1PRINTER_URL\s0
.IP "print_file \s-1DOCUMENT_URL, PRINTER_URL\s0" 4
.IX Item "print_file DOCUMENT_URL, PRINTER_URL"
Print file \s-1DOCUMENT_URL\s0 on \s-1PRINTER_URL\s0
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 4
chown
.IP "\(bu" 4
chmod
.IP "\(bu" 4
open_print_job
.IP "\(bu" 4
telldir
.IP "\(bu" 4
lseekdir
.SH "EXAMPLE"
.IX Header "EXAMPLE"
This module come with some scripts:
.IP "t/*.t" 4
.IX Item "t/*.t"
Just for check that this module is ok :\-)
.IP "smb2www\-2.cgi" 4
.IX Item "smb2www-2.cgi"
A \s-1CGI\s0 interface with these features:
.RS 4
.IP "\(bu" 4
browse workgroup ,share, dir
.IP "\(bu" 4
read file
.IP "\(bu" 4
upload file
.IP "\(bu" 4
create directory
.IP "\(bu" 4
unlink file, directory
.RE
.RS 4
.RE
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
The Filesys-SmbClient module is Copyright (c) 1999\-2003 Alain \s-1BARBET,\s0 France,
alian at cpan.org. All rights reserved.
.PP
You may distribute under the terms of either the \s-1GNU\s0 General
Public License or the Artistic License, as specified
in the Perl \s-1README\s0 file.