---
name: "Filesys::SmbClient"
section: "3pm"
platform: "linux"
package: "libfilesys-smbclient-perl"
version: "3.2-4+b5"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Filesys::SmbClient"
---

# Filesys::SmbClient(3pm)

Interface for access Samba filesystem with libsmclient.so

## NAME

Filesys::SmbClient - Interface for access Samba filesystem with 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);

  # ...
```

See section EXAMPLE for others scripts.

## DESCRIPTION

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

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.

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.

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

When a path is used, his scheme is :

```
  smb://server/share/rep/doc
```

## VERSION

`$Revision:` 3.2 $

## FONCTIONS

- new %hash

  Init connection Hash can have this keys:

  - •

    username

  - •

    password

  - •

    workgroup

  - •

    debug

  - •

    flags : See set\_flag

  Return instance of Filesys::SmbClient on succes, die with error else.

  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 Flag can be:

  - SMB\_CTX\_FLAG\_USE\_KERBEROS

    - SMB\_CTX\_FLAG\_FALLBACK\_AFTER\_KERBEROS

    - SMBCCTX\_FLAG\_NO\_AUTO\_ANONYMOUS\_LOGON

    ### 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.

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

### Directory

- mkdir FILENAME, MODE

  Create directory `$fname` with permissions set to `$mode`. Return 1 on success, else 0 is return and errno and $! is set.

  Example:

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

- rmdir FILENAME

  Erase directory `$fname`. Return 1 on success, else 0 is return and errno and $! is set. ($fname must be empty, else see  rmdir\_recurse).

  Example:

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

- rmdir\_recurse FILENAME

  Erase directory `$fname`. Return 1 on success, else 0 is return and errno and $! is set. Il `$fname` is not empty, all files and dir will be deleted.

  Example:

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

- opendir FILENAME

  Open directory `$fname`. Return file descriptor on succes, else 0 is return and $! is set.

- readdir FILEHANDLE

  Read a directory. In a list context, return the full content of the directory `$fd`, else return next element. Each elem is a name of a directory or files.

  Return 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

  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 :

  - SMBC\_WORKGROUP

    - SMBC\_SERVER

    - SMBC\_FILE\_SHARE

    - SMBC\_PRINTER\_SHARE

    - SMBC\_COMMS\_SHARE

    - SMBC\_IPC\_SHARE

    - SMBC\_DIR

    - SMBC\_FILE

    - SMBC\_LINK

    Return 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

  Close directory `$fd`.

### Files

- stat FILENAME

  Stat a file FILENAME. Return a list with info on success, else an empty list is return and $! is set.

  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

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

  Example:

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

- open FILENAME

  - open FILENAME, MODE

  Open file `$fname` with perm `$mode`. Return file descriptor on success, else 0 is return 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

  Read `$count` bytes of data on file descriptor `$fd`. It length is not set, 4096 bytes will be read.

  Return buffer read on success, undef at end of file, -1 is return on error and $! is set.

  FILEHANDLE must be open with open of this module.

- write FILEHANDLE, $buf

  - write FILEHANDLE, @buf

  Write `$buf` or `@buf` on file descriptor `$fd`. Return number of bytes wrote, else -1 is return and errno and $! is 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 others didn't work on libsmbclient.so

  FILEHANDLE must be open with open of this module.

- close FILEHANDLE

  Close file FILEHANDLE. Return 0 on success, else -1 is return and errno and $! is set.

- shutdown flag

  A wrapper around \`libsmbclient's \`smbc\_free\_context'.

  Close open files, release Samba connection, delete context, acquired during open\_\* calls.

  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

  Remove job number IDJOB on printer PRINTER\_URL

- print\_file DOCUMENT\_URL, PRINTER\_URL

  Print file DOCUMENT\_URL on PRINTER\_URL

## TODO

- •

  chown

- •

  chmod

- •

  open\_print\_job

- •

  telldir

- •

  lseekdir

## EXAMPLE

This module come with some scripts:

- t/\*.t

  Just for check 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

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

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