.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 2024-01-10 "perl v5.38.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
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 EXAMPLE 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 "make bin/libsmbclient.so" 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 SMB_CTX_FLAG_USE_KERBEROS 4
.IX Item "SMB_CTX_FLAG_USE_KERBEROS"
.PD 0
.IP SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS 4
.IX Item "SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS"
.IP SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON 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 FILENAME, MODE" 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 FILENAME" 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 FILENAME" 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 FILENAME" 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 FILEHANDLE" 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 FILEHANDLE" 4
.IX Item "readdir_struct FILEHANDLE"
Read a directory. In a list context, return the full content of
the directory FILEHANDLE, else return next element. Each element
is a ref to an array with type, name and comment. Type can be :
.RS 4
.IP SMBC_WORKGROUP 4
.IX Item "SMBC_WORKGROUP"
.PD 0
.IP SMBC_SERVER 4
.IX Item "SMBC_SERVER"
.IP SMBC_FILE_SHARE 4
.IX Item "SMBC_FILE_SHARE"
.IP SMBC_PRINTER_SHARE 4
.IX Item "SMBC_PRINTER_SHARE"
.IP SMBC_COMMS_SHARE 4
.IX Item "SMBC_COMMS_SHARE"
.IP SMBC_IPC_SHARE 4
.IX Item "SMBC_IPC_SHARE"
.IP SMBC_DIR 4
.IX Item "SMBC_DIR"
.IP SMBC_FILE 4
.IX Item "SMBC_FILE"
.IP SMBC_LINK 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 FILEHANDLE" 4
.IX Item "closedir FILEHANDLE"
Close directory \f(CW$fd\fR.
.SS Files
.IX Subsection "Files"
.IP "stat FILENAME" 4
.IX Item "stat FILENAME"
Stat a file FILENAME. 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 ID of owner
.IP \(bu 4
group ID 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 FILEHANDLE" 4
.IX Item "fstat FILEHANDLE"
Like stat, but on a file handle
.IP "rename OLDNAME,NEWNAME" 4
.IX Item "rename OLDNAME,NEWNAME"
Changes the name of a file; an existing file NEWNAME 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 FILENAME" 4
.IX Item "unlink FILENAME"
Unlink FILENAME. 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 FILENAME" 4
.IX Item "open FILENAME"
.PD 0
.IP "open FILENAME, MODE" 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 FILEHANDLE" 4
.IX Item "read FILEHANDLE"
.PD 0
.IP "read FILEHANDLE, LENGTH" 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
FILEHANDLE must be open with open of this module.
.ie n .IP "write FILEHANDLE, $buf" 4
.el .IP "write FILEHANDLE, \f(CW$buf\fR" 4
.IX Item "write FILEHANDLE, $buf"
.PD 0
.ie n .IP "write FILEHANDLE, @buf" 4
.el .IP "write FILEHANDLE, \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
FILEHANDLE must be open with open of this module.
.IP "seek FILEHANDLE, POS" 4
.IX Item "seek FILEHANDLE, POS"
Sets FILEHANDLE's position, just like the "fseek"
call of "stdio".  FILEHANDLE may be an expression
whose value gives the name of the filehandle.  The
values for WHENCE is always SEEK_SET because others
didn't work on libsmbclient.so
.Sp
FILEHANDLE must be open with open of this module.
.IP "close FILEHANDLE" 4
.IX Item "close FILEHANDLE"
Close file FILEHANDLE. 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
NOTE:
    \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 PRINTER_URL, IDJOB" 4
.IX Item "unlink_print_job PRINTER_URL, IDJOB"
Remove job number IDJOB on printer PRINTER_URL
.IP "print_file DOCUMENT_URL, PRINTER_URL" 4
.IX Item "print_file DOCUMENT_URL, PRINTER_URL"
Print file DOCUMENT_URL on PRINTER_URL
.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 CGI 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 BARBET, France,
alian at cpan.org. All rights reserved.
.PP
You may distribute under the terms of either the GNU General
Public License or the Artistic License, as specified
in the Perl README file.