NAME

Filesys::SmbClient - Interface for accessing Samba filesystem with libsmclient.so

SYNOPSIS

 use POSIX;
 use Filesys::SmbClient;
 
 my $smb = Filesys::SmbClient->new(username  => "alian",
                                    password  => "speed",
                                    workgroup => "alian",
                                    debug     => 10);
 
 # Read a file
 my $fh = $smb->open("smb://jupiter/doc/general.css", '0666');
 my $buf;
 while (defined($fh->read($buf,50))) {print $buf; }
 $fh->close();
  
  # ...

Models

There are 4 different interfaces to Samba. The first one is the "raw" access to the libsmbclient.so functions (well, most of them). This is done via:

 use Filesys::SmbClient qw(:raw);

Because the XS stub functions map directly to the libsmbclient.so API and are subject to change, using these methods is strongly discouraged.

The second method is using the Tie::Handle class, and is kept for backward compatibility. This is a very limited interface, and may not be maintained much longer.

The last two interfaces are symmetrical and use the IO::Handle and IO::Dir base classes for the derived classes FileHandle and DirHandle.

Construction is done via the parent class, firstly:

 my $fh = $smb->open("a/b/foo.txt");

to open a file for reading (or with slight modification, for writing). The class's own open method isn't available, since opening is done via the parent object. The IO::Handle methods that aren't implemented are:

• open - use parent open method

• eof

• fileno

• getc

• sysread

• syswrite

• fdopen

• getline

• getline

• ungetc

• clearerr

• sync

• flush - no-op

• blocking

• untaint

The second construction is done similarly, for directories:

  my $dh = $smb->opendir("usr/spool");

and again, not all methods map onto SMB. Omitted methods are:

• open - use parent open method

See the IO::Handle and IO::Dir modules' documentation for more info.

DESCRIPTION

Provide interface to access routine defined in libsmbclient.so provided with Samba.

With the 4.0 release of this package, you are required to have Samba 3.4.5 or later.

If you want to use filehandle with this module, you need Perl 5.6 or later.

When a path is used, the URL is represented as:

  smb://server/share/rep/doc

VERSION

$Revision: 3.99 $

FUNCTIONS

Construct a Filesys::SmbClient object:

• new %hash

  The hash can have the keys:

  • username

  • password

  • workgroup

  • debug

  • flags - See set_flag

Returns an instance of Filesys::SmbClient on success, or undef otherwise.

Example:

 my $smb = new Filesys::SmbClient(username  => "alian",
                                  password  => "speed", 
                                  workgroup => "alian",
                                  debug     => 10);

set_flag

Set flag for smb connection. See _SMBCCTX->flags in libsmclient.h Flags can be a combination of:

SMB_CTX_FLAG_USE_KERBEROS

SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS

SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON

The returned object can then be used with "open" to construct a FileHandle, with "opendir" to construct a DirHandle, or with "tie" to access the legacy Tie::Handle API.

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, tell, getc, open, close, read. See perldoc for usage.

Example:

 local *FD;
 tie(*FD, 'Filesys::SmbClient');
 open(FD,"smb://jupiter/doc/test")
     or print "Can't open file:", $!, "\n";
 while(<FD>) { print $_; }
 close(FD);

or

 local *FD;
 tie(*FD, 'Filesys::SmbClient');
 open(FD,">smb://jupiter/doc/test")
     or print "Can't create file:", $!, "\n";
 print FD "Samba test","\n";
 printf FD "%s", "And that work !\n";
 close(FD);

Miscellany

mkdir FILENAME, MODE

Creates FILENAME, with permissions as MODE (as modified by umask). Return 1 on success, otherwise 0 is return and errno and $! is set.

Example:

 $smb->mkdir("smb://jupiter/doc/toto",'0666') 
     or print "Error mkdir: ", $!, "\n";

rmdir DIRNAME

Unlink DIRNAME. Return 1 on success, otherwise 0 is return and errno and $! is set. The directory must be empty.

Example:

 $smb->rmdir("smb://jupiter/doc/toto")
     or print "Error rmdir: ", $!, "\n";

unlink FILENAME

Unlink FILENAME. Return 1 on success, otherwise 0 is return and errno and $! is set.

stat FILENAME

Returns the following about the named file or directory:

• device number

• inode number

• permission modes

• number of links

• user identifier

• group identifier

• remote device number

• size

• block size

• blocks

• access time

• modification time

• creation time

Note that because of filesystem "holes" the reported size may be larger than the product of block size x blocks.

On failure, an empty list is returned and errno and $! is set.

rename OLDNAME,NEWNAME

Renames a file or directory; an existing file NEWNAME will be clobbered. Returns 1 for success, 0 otherwise, with $! set.

Example:

 $smb->rename("smb://jupiter/doc/toto","smb://jupiter/doc/tata")
     or print "Can't rename file:", $!, "\n";

TODO

Revisit the list of IO::Handle methods that aren't implemented and see which ones can be added.

COPYRIGHT

The Filesys-SmbClient module is Copyright (c) 1999-2003 Alain BARBET, France, alian at cpan.org. All rights reserved.

Assumed in 2010 by Philip Prindeville.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

cpanm Filesys::SmbClient

perl -MCPAN -e shell
install Filesys::SmbClient