SmbClient(3pm)

📦

version 3.2 · 6 versions

🌸 SmbClient(3pm) 🌸

okay bestie, welcome to SmbClient from the User Contributed Perl Documentation crew 💖 this is the page for Filesys::SmbClient, and yes we are gonna get you fluent in talking to Samba shares from Perl. grab a strawberry drink 🍓 and let's go.

✨ NAME ✨

Filesys::SmbClient — the interface that lets you access a Samba filesystem through libsmclient.so 🦋

🎀 SYNOPSIS 🎀

  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", '0666');
  while (defined(my $l= $smb->read($fd,50))) {print $l; }
  $smb->close(fd);

  # ...

more scripts live in the EXAMPLE section, keep scrolling 💅

💜 DESCRIPTION 💜

It gives you an interface to reach the routines defined in libsmbclient.so, which ships with Samba. periodt.

So here's the tea: since the 3.0 release of this package, you need at least samba-3.0.2. If you're on an older Samba, use Filesys::SmbClient version 1.x instead, no cap.

For the old releases and the 2.x line: this library is available in the Samba source, but it is not built by default 🙈. So you do make bin/libsmbclient.so in the sources directory of Samba to build these libraries. Then copy source/include/libsmbclient.h to /usr/local/samba/include and source/bin/libsmbclient.so to /usr/local/samba/lib before you install this module. yes it's a whole little ritual, do it anyway ✨

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

Whenever a path shows up, its scheme is:

  smb://server/share/rep/doc

⭐ VERSION ⭐

  $Revision: 3.2 $

👑 FONCTIONS 👑

(yes bestie it's spelled like that, we respect it 💅)

🫶 new %hash

Starts up the connection. The hash can have these keys:

username
password
workgroup
debug
flags — peep set_flag for this one

It returns an instance of Filesys::SmbClient on success, and dies with an error otherwise 😭

Example:

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

🌈 set_flag

Sets a flag for the smb connection. Check _SMBCCTX->flags in libsmclient.h. A flag can be:

SMB_CTX_FLAG_USE_KERBEROS
SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS
SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON

🧚 Tie Filesys::SmbClient filehandle

Heads up: this didn't work before 5.005_64. Why? I don't know, and honestly the vibes are mysterious 🌸. Once you've tied a filehandle with Filesys::SmbClient, you can call the classic filehandle methods: print, printf, seek, syswrite, 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);

  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);

💖 Directory 💖

`mkdir FILENAME, MODE`

Creates directory $fname with permissions set to $mode. Returns 1 on success, otherwise 0 is returned and errno and $! are set.

Example:

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

`rmdir FILENAME`

Erases directory $fname. Returns 1 on success, otherwise 0 is returned and errno and $! are set. ($fname must be empty, else see rmdir_recurse.)

Example:

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

`rmdir_recurse FILENAME`

Erases directory $fname. Returns 1 on success, otherwise 0 is returned and errno and $! are set. If $fname is not empty, all files and dirs will be deleted. yeah it goes feral like that 💀

Example:

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

`opendir FILENAME`

Opens directory $fname. Returns a file descriptor on success, otherwise 0 is returned and $! is set.

`readdir FILEHANDLE`

Reads a directory. In a list context it returns the full content of the directory $fd, otherwise it returns the next element. Each elem is a name of a directory or file.

Returns undef at end of directory.

Example:

  my $fd = $smb->opendir("smb://jupiter/doc");
  foreach my $n ($smb->readdir($fd)) {print $n,"\n";}
  close($fd);

`readdir_struct FILEHANDLE`

Reads a directory. In a list context it returns the full content of the directory FILEHANDLE, otherwise it returns the next element. Each element is a ref to an array with type, name and comment. Type can be:

SMBC_WORKGROUP
SMBC_SERVER
SMBC_FILE_SHARE
SMBC_PRINTER_SHARE
SMBC_COMMS_SHARE
SMBC_IPC_SHARE
SMBC_DIR
SMBC_FILE
SMBC_LINK

Returns undef at end of directory.

Example:

  my $fd = $smb->opendir("smb://jupiter/doc");
  while (my $f = $smb->readdir_struct($fd)) {
    if ($f->[0] == SMBC_DIR) {print "Directory ",$f->[1],"\n";}
    elsif ($f->[0] == SMBC_FILE) {print "File ",$f->[1],"\n";}
    # ...
  }
  close($fd);

`closedir FILEHANDLE`

Closes directory $fd.

🦋 Files 🦋

`stat FILENAME`

Stats a file FILENAME. Returns a list with info on success, otherwise an empty list is returned and $! is set.

The list is made with:

device
inode
protection
number of hard links
user ID of owner
group ID of owner
device type (if inode device)
total size, in bytes
blocksize for filesystem I/O
number of blocks allocated
time of last access
time of last modification
time of last change

Example:

  my @tab = $smb->stat("smb://jupiter/doc/tata");
  if ($#tab == 0) { print "Erreur in stat:", $!, "\n"; }
  else {
    for (10..12) {$tab[$_] = localtime($tab[$_]);}
    print join("\n",@tab);
  }

`fstat FILEHANDLE`

Like stat, but on a file handle.

`rename OLDNAME,NEWNAME`

Changes the name of a file; an existing file NEWNAME will be clobbered 😭. Returns true for success, false otherwise, with $! set.

Example:

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

`unlink FILENAME`

Unlinks FILENAME. Returns 1 on success, otherwise 0 is returned and errno and $! are set.

Example:

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

`open FILENAME`, `open FILENAME, MODE`

Opens file $fname with perm $mode. Returns a file descriptor on success, otherwise 0 is returned and $! is set.

Example:

  my $fd = $smb->open("smb://jupiter/doc/test", 0666)
    or print "Can't read file:", $!, "\n";

  my $fd = $smb->open(">smb://jupiter/doc/test", 0666)
    or print "Can't create file:", $!, "\n";

  my $fd = $smb->open(">>smb://jupiter/doc/test", 0666)
    or print "Can't append to file:", $!, "\n";

`read FILEHANDLE`, `read FILEHANDLE, LENGTH`

Reads $count bytes of data on file descriptor $fd. If length is not set, 4096 bytes will be read.

Returns the buffer read on success, undef at end of file, and -1 is returned on error with $! set.

FILEHANDLE must be open with open of this module. no shortcuts bestie 💅

`write FILEHANDLE, $buf`, `write FILEHANDLE, @buf`

Writes $buf or @buf on file descriptor $fd. Returns the number of bytes wrote, otherwise -1 is returned and errno and $! are set.

Example:

  my $fd = $smb->open(">smb://jupiter/doc/test", 0666)
    or print "Can't create file:", $!, "\n";
  $smb->write($fd, "A test of write call")
    or print $!,"\n";
  $smb->close($fd);

FILEHANDLE must be open with open of this module.

`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 the others didn't work on libsmbclient.so. it's giving "we tried, we failed, we moved on" 💀

FILEHANDLE must be open with open of this module.

`close FILEHANDLE`

Closes file FILEHANDLE. Returns 0 on success, otherwise -1 is returned and errno and $! are set.

`shutdown flag`

A wrapper around libsmbclient's smbc_free_context.

Closes open files, releases the Samba connection, and deletes the context acquired during open_* calls. iconically tidy ✨

Example:

    $smb->shutdown(0); # Gracefully close connection
    $sbm->shutdown(1); # Forcibly close files and connection

NOTE: shutdown(1) may cause complaints about talloc memory leaks, if there are currently no open files. 🙈

🎀 Print method 🎀

`unlink_print_job PRINTER_URL, IDJOB`

Removes job number IDJOB on printer PRINTER_URL.

`print_file DOCUMENT_URL, PRINTER_URL`

Prints file DOCUMENT_URL on PRINTER_URL.

🍓 TODO 🍓

stuff we still wanna do, manifesting ✨:

chown
chmod
open_print_job
telldir
lseekdir

💅 EXAMPLE 💅

This module comes with some scripts:

t/*.t — just for checking that this module is ok :-)
smb2www-2.cgi — a CGI interface with these features:
- browse workgroup, share, dir
- read file
- upload file
- create directory
- unlink file, directory

👑 COPYRIGHT 👑

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

and that's the whole page bestie 🫶 this was perl v5.42.3, dated 2026-08-19, and it lives under the name SmbClient(3pm). go slay some Samba shares 💖✨

📦 where this page comes from

ubuntu stonking: libfilesys-smbclient-perl 3.2-4build6 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

SmbClient(3pm)

🌸 SmbClient(3pm) 🌸

✨ NAME ✨

🎀 SYNOPSIS 🎀

💜 DESCRIPTION 💜

⭐ VERSION ⭐

👑 FONCTIONS 👑

🫶 new %hash

🌈 set_flag

🧚 Tie Filesys::SmbClient filehandle

💖 Directory 💖

mkdir FILENAME, MODE

rmdir FILENAME

rmdir_recurse FILENAME

opendir FILENAME

readdir FILEHANDLE

readdir_struct FILEHANDLE

closedir FILEHANDLE

🦋 Files 🦋

stat FILENAME

fstat FILEHANDLE

rename OLDNAME,NEWNAME

unlink FILENAME

open FILENAME, open FILENAME, MODE

read FILEHANDLE, read FILEHANDLE, LENGTH

write FILEHANDLE, $buf, write FILEHANDLE, @buf

seek FILEHANDLE, POS

close FILEHANDLE

shutdown flag

🎀 Print method 🎀

unlink_print_job PRINTER_URL, IDJOB

print_file DOCUMENT_URL, PRINTER_URL

🍓 TODO 🍓

💅 EXAMPLE 💅

👑 COPYRIGHT 👑

`mkdir FILENAME, MODE`

`rmdir FILENAME`

`rmdir_recurse FILENAME`

`opendir FILENAME`

`readdir FILEHANDLE`

`readdir_struct FILEHANDLE`

`closedir FILEHANDLE`

`stat FILENAME`

`fstat FILEHANDLE`

`rename OLDNAME,NEWNAME`

`unlink FILENAME`

`open FILENAME`, `open FILENAME, MODE`

`read FILEHANDLE`, `read FILEHANDLE, LENGTH`

`write FILEHANDLE, $buf`, `write FILEHANDLE, @buf`

`seek FILEHANDLE, POS`

`close FILEHANDLE`

`shutdown flag`

`unlink_print_job PRINTER_URL, IDJOB`

`print_file DOCUMENT_URL, PRINTER_URL`