source/include/libsmbclient.h

   1 /*=====================================================================
   2   Unix SMB/Netbios implementation.
   3   SMB client library API definitions
   4   Copyright (C) Andrew Tridgell 1998
   5   Copyright (C) Richard Sharpe 2000
   6   Copyright (C) John Terpsra 2000
   7   Copyright (C) Tom Jansen (Ninja ISD) 2002
   8   Copyright (C) Derrell Lipman 2003
   9
  10
  11   This program is free software; you can redistribute it and/or modify
  12   it under the terms of the GNU General Public License as published by
  13   the Free Software Foundation; either version 2 of the License, or
  14   (at your option) any later version.
  15
  16   This program is distributed in the hope that it will be useful,
  17   but WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19   GNU General Public License for more details.
  20
  21   You should have received a copy of the GNU General Public License
  22   along with this program; if not, write to the Free Software
  23   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  24   =====================================================================*/
  25
  26 #ifndef SMBCLIENT_H_INCLUDED
  27 #define SMBCLIENT_H_INCLUDED
  28
  29 /*-------------------------------------------------------------------*/
  30 /* The following are special comments to instruct DOXYGEN (automated
  31  * documentation tool:
  32 */
  33 /** \defgroup libsmbclient
  34 */
  35 /** \defgroup structure Data Structures Type and Constants
  36 *   \ingroup libsmbclient
  37 *   Data structures, types, and constants
  38 */
  39 /** \defgroup callback Callback function types
  40 *   \ingroup libsmbclient
  41 *   Callback functions
  42 */
  43 /** \defgroup file File Functions
  44 *   \ingroup libsmbclient
  45 *   Functions used to access individual file contents
  46 */
  47 /** \defgroup directory Directory Functions
  48 *   \ingroup libsmbclient
  49 *   Functions used to access directory entries
  50 */
  51 /** \defgroup attribute Attributes Functions
  52 *   \ingroup libsmbclient
  53 *   Functions used to view or change file and directory attributes
  54 */
  55 /** \defgroup print Print Functions
  56 *   \ingroup libsmbclient
  57 *   Functions used to access printing functionality
  58 */
  59 /** \defgroup misc Miscellaneous Functions
  60 *   \ingroup libsmbclient
  61 *   Functions that don't fit in to other categories
  62 */
  63 /*-------------------------------------------------------------------*/
  64
  65 /* Make sure we have the following includes for now ... */
  66 #include <sys/types.h>
  67 #include <sys/stat.h>
  68 #include <fcntl.h>
  69 #include <utime.h>
  70
  71 #define SMBC_CTX_VERSION        1
  72
  73 #define SMBC_BASE_FD        10000 /* smallest file descriptor returned */
  74
  75 #define SMBC_WORKGROUP      1
  76 #define SMBC_SERVER         2
  77 #define SMBC_FILE_SHARE     3
  78 #define SMBC_PRINTER_SHARE  4
  79 #define SMBC_COMMS_SHARE    5
  80 #define SMBC_IPC_SHARE      6
  81 #define SMBC_DIR            7
  82 #define SMBC_FILE           8
  83 #define SMBC_LINK           9
  84
  85 /**@ingroup structure
  86  * Structure that represents a directory entry.
  87  *
  88  */
  89 struct smbc_dirent
  90 {
  91         /** Type of entity.
  92             SMBC_WORKGROUP=1,
  93             SMBC_SERVER=2,
  94             SMBC_FILE_SHARE=3,
  95             SMBC_PRINTER_SHARE=4,
  96             SMBC_COMMS_SHARE=5,
  97             SMBC_IPC_SHARE=6,
  98             SMBC_DIR=7,
  99             SMBC_FILE=8,
 100             SMBC_LINK=9,*/
 101         unsigned int smbc_type;
 102
 103         /** Length of this smbc_dirent in bytes
 104          */
 105         unsigned int dirlen;
 106         /** The length of the comment string in bytes (includes null
 107          *  terminator)
 108          */
 109         unsigned int commentlen;
 110         /** Points to the null terminated comment string
 111          */
 112         char *comment;
 113         /** The length of the name string in bytes (includes null
 114          *  terminator)
 115          */
 116         unsigned int namelen;
 117         /** Points to the null terminated name string
 118          */
 119         char name[1];
 120 };
 121
 122 /*
 123  * Flags for smbc_setxattr()
 124  *   Specify a bitwise OR of these, or 0 to add or replace as necessary
 125  */
 126 #define SMBC_XATTR_FLAG_CREATE       0x1 /* fail if attr already exists */
 127 #define SMBC_XATTR_FLAG_REPLACE      0x2 /* fail if attr does not exist */
 128
 129
 130 /*
 131  * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the
 132  * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or
 133  * "system.*") is specified.
 134  */
 135 #define SMBC_DOS_MODE_READONLY       0x01
 136 #define SMBC_DOS_MODE_HIDDEN         0x02
 137 #define SMBC_DOS_MODE_SYSTEM         0x04
 138 #define SMBC_DOS_MODE_VOLUME_ID      0x08
 139 #define SMBC_DOS_MODE_DIRECTORY      0x10
 140 #define SMBC_DOS_MODE_ARCHIVE        0x20
 141
 142
 143 #ifndef ENOATTR
 144 # define ENOATTR ENOENT        /* No such attribute */
 145 #endif
 146
 147
 148
 149
 150 /**@ingroup structure
 151  * Structure that represents a print job.
 152  *
 153  */
 154 #ifndef _CLIENT_H
 155 struct print_job_info
 156 {
 157         /** numeric ID of the print job
 158          */
 159         unsigned short id;
 160
 161         /** represents print job priority (lower numbers mean higher priority)
 162          */
 163         unsigned short priority;
 164
 165         /** Size of the print job
 166          */
 167         size_t size;
 168
 169         /** Name of the user that owns the print job
 170          */
 171         char user[128];
 172
 173         /** Name of the print job. This will have no name if an anonymous print
 174          *  file was opened. Ie smb://server/printer
 175          */
 176         char name[128];
 177
 178         /** Time the print job was spooled
 179          */
 180         time_t t;
 181 };
 182 #endif /* _CLIENT_H */
 183
 184
 185 /**@ingroup structure
 186  * Server handle
 187  */
 188 typedef struct _SMBCSRV  SMBCSRV;
 189
 190 /**@ingroup structure
 191  * File or directory handle
 192  */
 193 typedef struct _SMBCFILE SMBCFILE;
 194
 195 /**@ingroup structure
 196  * File or directory handle
 197  */
 198 typedef struct _SMBCCTX SMBCCTX;
 199
 200
 201
 202
 203
 204 /**@ingroup callback
 205  * Authentication callback function type.
 206  *
 207  * Type for the the authentication function called by the library to
 208  * obtain authentication credentals
 209  *
 210  * @param srv       Server being authenticated to
 211  *
 212  * @param shr       Share being authenticated to
 213  *
 214  * @param wg        Pointer to buffer containing a "hint" for the
 215  *                  workgroup to be authenticated.  Should be filled in
 216  *                  with the correct workgroup if the hint is wrong.
 217  *
 218  * @param wglen     The size of the workgroup buffer in bytes
 219  *
 220  * @param un        Pointer to buffer containing a "hint" for the
 221  *                  user name to be use for authentication. Should be
 222  *                  filled in with the correct workgroup if the hint is
 223  *                  wrong.
 224  *
 225  * @param unlen     The size of the username buffer in bytes
 226  *
 227  * @param pw        Pointer to buffer containing to which password
 228  *                  copied
 229  *
 230  * @param pwlen     The size of the password buffer in bytes
 231  *
 232  */
 233 typedef void (*smbc_get_auth_data_fn)(const char *srv,
 234                                       const char *shr,
 235                                       char *wg, int wglen,
 236                                       char *un, int unlen,
 237                                       char *pw, int pwlen);
 238
 239
 240 /**@ingroup callback
 241  * Print job info callback function type.
 242  *
 243  * @param i         pointer to print job information structure
 244  *
 245  */
 246 typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
 247
 248
 249 /**@ingroup callback
 250  * Check if a server is still good
 251  *
 252  * @param c         pointer to smb context
 253  *
 254  * @param srv       pointer to server to check
 255  *
 256  * @return          0 when connection is good. 1 on error.
 257  *
 258  */
 259 typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
 260
 261 /**@ingroup callback
 262  * Remove a server if unused
 263  *
 264  * @param c         pointer to smb context
 265  *
 266  * @param srv       pointer to server to remove
 267  *
 268  * @return          0 on success. 1 on failure.
 269  *
 270  */
 271 typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
 272
 273
 274 /**@ingroup callback
 275  * Add a server to the cache system
 276  *
 277  * @param c         pointer to smb context
 278  *
 279  * @param srv       pointer to server to add
 280  *
 281  * @param server    server name
 282  *
 283  * @param share     share name
 284  *
 285  * @param workgroup workgroup used to connect
 286  *
 287  * @param username  username used to connect
 288  *
 289  * @return          0 on success. 1 on failure.
 290  *
 291  */
 292 typedef int (*smbc_add_cached_srv_fn)   (SMBCCTX * c, SMBCSRV *srv,
 293                                     const char * server, const char * share,
 294                                     const char * workgroup, const char * username);
 295
 296 /**@ingroup callback
 297  * Look up a server in the cache system
 298  *
 299  * @param c         pointer to smb context
 300  *
 301  * @param server    server name to match
 302  *
 303  * @param share     share name to match
 304  *
 305  * @param workgroup workgroup to match
 306  *
 307  * @param username  username to match
 308  *
 309  * @return          pointer to SMBCSRV on success. NULL on failure.
 310  *
 311  */
 312 typedef SMBCSRV * (*smbc_get_cached_srv_fn)   (SMBCCTX * c, const char * server,
 313                                                const char * share, const char * workgroup,
 314                                                const char * username);
 315
 316 /**@ingroup callback
 317  * Check if a server is still good
 318  *
 319  * @param c         pointer to smb context
 320  *
 321  * @param srv       pointer to server to remove
 322  *
 323  * @return          0 when found and removed. 1 on failure.
 324  *
 325  */
 326 typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
 327
 328
 329 /**@ingroup callback
 330  * Try to remove all servers from the cache system and disconnect
 331  *
 332  * @param c         pointer to smb context
 333  *
 334  * @return          0 when found and removed. 1 on failure.
 335  *
 336  */
 337 typedef int (*smbc_purge_cached_fn)     (SMBCCTX * c);
 338
 339
 340
 341
 342 /**@ingroup structure
 343  * Structure that contains a client context information
 344  * This structure is know as SMBCCTX
 345  */
 346 struct _SMBCCTX {
 347         /** debug level
 348          */
 349         int     debug;
 350
 351         /** netbios name used for making connections
 352          */
 353         char * netbios_name;
 354
 355         /** workgroup name used for making connections
 356          */
 357         char * workgroup;
 358
 359         /** username used for making connections
 360          */
 361         char * user;
 362
 363         /** timeout used for waiting on connections / response data (in milliseconds)
 364          */
 365         int timeout;
 366
 367         /** callable functions for files:
 368          * For usage and return values see the smbc_* functions
 369          */
 370         SMBCFILE * (*open)    (SMBCCTX *c, const char *fname, int flags, mode_t mode);
 371         SMBCFILE * (*creat)   (SMBCCTX *c, const char *path, mode_t mode);
 372         ssize_t    (*read)    (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
 373         ssize_t    (*write)   (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
 374         int        (*unlink)  (SMBCCTX *c, const char *fname);
 375         int        (*rename)  (SMBCCTX *ocontext, const char *oname,
 376                                SMBCCTX *ncontext, const char *nname);
 377         off_t      (*lseek)   (SMBCCTX *c, SMBCFILE * file, off_t offset, int whence);
 378         int        (*stat)    (SMBCCTX *c, const char *fname, struct stat *st);
 379         int        (*fstat)   (SMBCCTX *c, SMBCFILE *file, struct stat *st);
 380         int        (*close)   (SMBCCTX *c, SMBCFILE *file);
 381
 382         /** callable functions for dirs
 383          */
 384         SMBCFILE * (*opendir) (SMBCCTX *c, const char *fname);
 385         int        (*closedir)(SMBCCTX *c, SMBCFILE *dir);
 386         struct smbc_dirent * (*readdir)(SMBCCTX *c, SMBCFILE *dir);
 387         int        (*getdents)(SMBCCTX *c, SMBCFILE *dir,
 388                                struct smbc_dirent *dirp, int count);
 389         int        (*mkdir)   (SMBCCTX *c, const char *fname, mode_t mode);
 390         int        (*rmdir)   (SMBCCTX *c, const char *fname);
 391         off_t      (*telldir) (SMBCCTX *c, SMBCFILE *dir);
 392         int        (*lseekdir)(SMBCCTX *c, SMBCFILE *dir, off_t offset);
 393         int        (*fstatdir)(SMBCCTX *c, SMBCFILE *dir, struct stat *st);
 394         int        (*chmod)(SMBCCTX *c, const char *fname, mode_t mode);
 395         int        (*utimes)(SMBCCTX *c,
 396                              const char *fname, struct timeval *tbuf);
 397         int        (*setxattr)(SMBCCTX *context,
 398                                const char *fname,
 399                                const char *name,
 400                                const void *value,
 401                                size_t size,
 402                                int flags);
 403         int        (*getxattr)(SMBCCTX *context,
 404                                const char *fname,
 405                                const char *name,
 406                                const void *value,
 407                                size_t size);
 408         int        (*removexattr)(SMBCCTX *context,
 409                                   const char *fname,
 410                                   const char *name);
 411         int        (*listxattr)(SMBCCTX *context,
 412                                 const char *fname,
 413                                 char *list,
 414                                 size_t size);
 415
 416         /** callable functions for printing
 417          */
 418         int        (*print_file)(SMBCCTX *c_file, const char *fname,
 419                                  SMBCCTX *c_print, const char *printq);
 420         SMBCFILE * (*open_print_job)(SMBCCTX *c, const char *fname);
 421         int        (*list_print_jobs)(SMBCCTX *c, const char *fname, smbc_list_print_job_fn fn);
 422         int        (*unlink_print_job)(SMBCCTX *c, const char *fname, int id);
 423
 424
 425         /** Callbacks
 426          * These callbacks _always_ have to be initialized because they will not be checked
 427          * at dereference for increased speed.
 428          */
 429         struct _smbc_callbacks {
 430                 /** authentication function callback: called upon auth requests
 431                  */
 432                 smbc_get_auth_data_fn auth_fn;
 433
 434                 /** check if a server is still good
 435                  */
 436                 smbc_check_server_fn check_server_fn;
 437
 438                 /** remove a server if unused
 439                  */
 440                 smbc_remove_unused_server_fn remove_unused_server_fn;
 441
 442                 /** Cache subsystem
 443                  * For an example cache system see samba/source/libsmb/libsmb_cache.c
 444                  * Cache subsystem functions follow.
 445                  */
 446
 447                 /** server cache addition
 448                  */
 449                 smbc_add_cached_srv_fn add_cached_srv_fn;
 450
 451                 /** server cache lookup
 452                  */
 453                 smbc_get_cached_srv_fn get_cached_srv_fn;
 454
 455                 /** server cache removal
 456                  */
 457                 smbc_remove_cached_srv_fn remove_cached_srv_fn;
 458
 459                 /** server cache purging, try to remove all cached servers (disconnect)
 460                  */
 461                 smbc_purge_cached_fn purge_cached_fn;
 462         } callbacks;
 463
 464
 465         /** Space to store private data of the server cache.
 466          */
 467         struct smbc_server_cache * server_cache;
 468
 469         /** INTERNAL DATA
 470          * do _NOT_ touch this from your program !
 471          */
 472         struct smbc_internal_data * internal;
 473
 474         int flags;
 475 };
 476
 477 /* Flags for SMBCCTX->flags */
 478 #define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
 479 #define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
 480 #define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2) /* don't try to do automatic anon login */
 481 #define SMBCCTX_FLAG_CTXVER (1 << 3 ) /* internal flag used to define _SMBCCTX version */
 482
 483 /**@ingroup misc
 484  * Create a new SBMCCTX (a context).
 485  *
 486  * Must be called before the context is passed to smbc_context_init()
 487  *
 488  * @return          The given SMBCCTX pointer on success, NULL on error with errno set:
 489  *                  - ENOMEM Out of memory
 490  *
 491  * @see             smbc_free_context(), smbc_init_context()
 492  *
 493  * @note            Do not forget to smbc_init_context() the returned SMBCCTX pointer !
 494  */
 495 #ifdef __cplusplus
 496 extern "C" {
 497 #endif
 498 SMBCCTX * smbc_new_context(void);
 499 #ifdef __cplusplus
 500 }
 501 #endif
 502
 503 /**@ingroup misc
 504  * Delete a SBMCCTX (a context) acquired from smbc_new_context().
 505  *
 506  * The context will be deleted if possible.
 507  *
 508  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
 509  *
 510  * @param shutdown_ctx   If 1, all connections and files will be closed even if they are busy.
 511  *
 512  *
 513  * @return          Returns 0 on succes. Returns 1 on failure with errno set:
 514  *                  - EBUSY Server connections are still used, Files are open or cache
 515  *                          could not be purged
 516  *                  - EBADF context == NULL
 517  *
 518  * @see             smbc_new_context()
 519  *
 520  * @note            It is advised to clean up all the contexts with shutdown_ctx set to 1
 521  *                  just before exit()'ing. When shutdown_ctx is 0, this function can be
 522  *                  use in periodical cleanup functions for example.
 523  */
 524 #ifdef __cplusplus
 525 extern "C" {
 526 #endif
 527 int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
 528 #ifdef __cplusplus
 529 }
 530 #endif
 531
 532 /**@ingroup misc
 533  * Initialize a SBMCCTX (a context).
 534  *
 535  * Must be called before using any SMBCCTX API function
 536  *
 537  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
 538  *
 539  * @return          A pointer to the given SMBCCTX on success, NULL on error with errno set:
 540  *                  - EBADF  NULL context given
 541  *                  - ENOMEM Out of memory
 542  *                  - ENOENT The smb.conf file would not load
 543  *
 544  * @see             smbc_new_context()
 545  *
 546  * @note            my_context = smbc_init_context(smbc_new_context()) is perfectly safe,
 547  *                  but it might leak memory on smbc_context_init() failure. Avoid this.
 548  *                  You'll have to call smbc_free_context() yourself on failure.
 549  */
 550 #ifdef __cplusplus
 551 extern "C" {
 552 #endif
 553 SMBCCTX * smbc_init_context(SMBCCTX * context);
 554 #ifdef __cplusplus
 555 }
 556 #endif
 557
 558 /**@ingroup misc
 559  * Initialize the samba client library.
 560  *
 561  * Must be called before using any of the smbclient API function
 562  *
 563  * @param fn        The function that will be called to obtaion
 564  *                  authentication credentials.
 565  *
 566  * @param debug     Allows caller to set the debug level. Can be
 567  *                  changed in smb.conf file. Allows caller to set
 568  *                  debugging if no smb.conf.
 569  *
 570  * @return          0 on success, < 0 on error with errno set:
 571  *                  - ENOMEM Out of memory
 572  *                  - ENOENT The smb.conf file would not load
 573  *
 574  */
 575
 576 #ifdef __cplusplus
 577 extern "C" {
 578 #endif
 579 int smbc_init(smbc_get_auth_data_fn fn, int debug);
 580 #ifdef __cplusplus
 581 }
 582 #endif
 583
 584 /**@ingroup misc
 585  * Set or retrieve the compatibility library's context pointer
 586  *
 587  * @param context   New context to use, or NULL.  If a new context is provided,
 588  *                  it must have allocated with smbc_new_context() and
 589  *                  initialized with smbc_init_context(), followed, optionally,
 590  *                  by some manual changes to some of the non-internal fields.
 591  *
 592  * @return          The old context.
 593  *
 594  * @see             smbc_new_context(), smbc_init_context(), smbc_init()
 595  *
 596  * @note            This function may be called prior to smbc_init() to force
 597  *                  use of the next context without any internal calls to
 598  *                  smbc_new_context() or smbc_init_context().  It may also
 599  *                  be called after smbc_init() has already called those two
 600  *                  functions, to replace the existing context with a new one.
 601  *                  Care should be taken, in this latter case, to ensure that
 602  *                  the server cache and any data allocated by the
 603  *                  authentication functions have been freed, if necessary.
 604  */
 605
 606 #ifdef __cplusplus
 607 extern "C" {
 608 #endif
 609 SMBCCTX * smbc_set_context(SMBCCTX * new_context);
 610 #ifdef __cplusplus
 611 }
 612 #endif
 613
 614 /**@ingroup file
 615  * Open a file on an SMB server.
 616  *
 617  * @param furl      The smb url of the file to be opened.
 618  *
 619  * @param flags     Is one of O_RDONLY, O_WRONLY or O_RDWR which
 620  *                  request opening  the  file  read-only,write-only
 621  *                  or read/write. flags may also be bitwise-or'd with
 622  *                  one or  more of  the following:
 623  *                  O_CREAT - If the file does not exist it will be
 624  *                  created.
 625  *                  O_EXCL - When  used with O_CREAT, if the file
 626  *                  already exists it is an error and the open will
 627  *                  fail.
 628  *                  O_TRUNC - If the file already exists it will be
 629  *                  truncated.
 630  *                  O_APPEND The  file  is  opened  in  append mode
 631  *
 632  * @param mode      mode specifies the permissions to use if a new
 633  *                  file is created.  It  is  modified  by  the
 634  *                  process's umask in the usual way: the permissions
 635  *                  of the created file are (mode & ~umask)
 636  *
 637  *                  Not currently use, but there for future use.
 638  *                  We will map this to SYSTEM, HIDDEN, etc bits
 639  *                  that reverses the mapping that smbc_fstat does.
 640  *
 641  * @return          Valid file handle, < 0 on error with errno set:
 642  *                  - ENOMEM  Out of memory
 643  *                  - EINVAL if an invalid parameter passed, like no
 644  *                  file, or smbc_init not called.
 645  *                  - EEXIST  pathname already exists and O_CREAT and
 646  *                  O_EXCL were used.
 647  *                  - EISDIR  pathname  refers  to  a  directory  and
 648  *                  the access requested involved writing.
 649  *                  - EACCES  The requested access to the file is not
 650  *                  allowed
 651  *                  - ENODEV The requested share does not exist
 652  *                  - ENOTDIR A file on the path is not a directory
 653  *                  - ENOENT  A directory component in pathname does
 654  *                  not exist.
 655  *
 656  * @see             smbc_creat()
 657  *
 658  * @note            This call uses an underlying routine that may create
 659  *                  a new connection to the server specified in the URL.
 660  *                  If the credentials supplied in the URL, or via the
 661  *                  auth_fn in the smbc_init call, fail, this call will
 662  *                  try again with an empty username and password. This
 663  *                  often gets mapped to the guest account on some machines.
 664  */
 665 #ifdef __cplusplus
 666 extern "C" {
 667 #endif
 668 int smbc_open(const char *furl, int flags, mode_t mode);
 669 #ifdef __cplusplus
 670 }
 671 #endif
 672
 673 /**@ingroup file
 674  * Create a file on an SMB server.
 675  *
 676  * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
 677  *
 678  * @param furl      The smb url of the file to be created
 679  *
 680  * @param mode      mode specifies the permissions to use if  a  new
 681  *                  file is created.  It  is  modified  by  the
 682  *                  process's umask in the usual way: the permissions
 683  *                  of the created file are (mode & ~umask)
 684  *
 685  *                  NOTE, the above is not true. We are dealing with
 686  *                  an SMB server, which has no concept of a umask!
 687  *
 688  * @return          Valid file handle, < 0 on error with errno set:
 689  *                  - ENOMEM  Out of memory
 690  *                  - EINVAL if an invalid parameter passed, like no
 691  *                  file, or smbc_init not called.
 692  *                  - EEXIST  pathname already exists and O_CREAT and
 693  *                  O_EXCL were used.
 694  *                  - EISDIR  pathname  refers  to  a  directory  and
 695  *                  the access requested involved writing.
 696  *                  - EACCES  The requested access to the file is not
 697  *                  allowed
 698  *                  - ENOENT  A directory component in pathname does
 699  *                  not exist.
 700  *                  - ENODEV The requested share does not exist.
 701  * @see             smbc_open()
 702  *
 703  */
 704 #ifdef __cplusplus
 705 extern "C" {
 706 #endif
 707 int smbc_creat(const char *furl, mode_t mode);
 708 #ifdef __cplusplus
 709 }
 710 #endif
 711
 712 /**@ingroup file
 713  * Read from a file using an opened file handle.
 714  *
 715  * @param fd        Open file handle from smbc_open() or smbc_creat()
 716  *
 717  * @param buf       Pointer to buffer to recieve read data
 718  *
 719  * @param bufsize   Size of buf in bytes
 720  *
 721  * @return          Number of bytes read, < 0 on error with errno set:
 722  *                  - EISDIR fd refers to a directory
 723  *                  - EBADF  fd  is  not  a valid file descriptor or
 724  *                  is not open for reading.
 725  *                  - EINVAL fd is attached to an object which is
 726  *                  unsuitable for reading, or no buffer passed or
 727  *                  smbc_init not called.
 728  *
 729  * @see             smbc_open(), smbc_write()
 730  *
 731  */
 732 #ifdef __cplusplus
 733 extern "C" {
 734 #endif
 735 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
 736 #ifdef __cplusplus
 737 }
 738 #endif
 739
 740 /**@ingroup file
 741  * Write to a file using an opened file handle.
 742  *
 743  * @param fd        Open file handle from smbc_open() or smbc_creat()
 744  *
 745  * @param buf       Pointer to buffer to recieve read data
 746  *
 747  * @param bufsize   Size of buf in bytes
 748  *
 749  * @return          Number of bytes written, < 0 on error with errno set:
 750  *                  - EISDIR fd refers to a directory.
 751  *                  - EBADF  fd  is  not  a valid file descriptor or
 752  *                  is not open for reading.
 753  *                  - EINVAL fd is attached to an object which is
 754  *                  unsuitable for reading, or no buffer passed or
 755  *                  smbc_init not called.
 756  *
 757  * @see             smbc_open(), smbc_read()
 758  *
 759  */
 760 #ifdef __cplusplus
 761 extern "C" {
 762 #endif
 763 ssize_t smbc_write(int fd, void *buf, size_t bufsize);
 764 #ifdef __cplusplus
 765 }
 766 #endif
 767
 768 /**@ingroup file
 769  * Seek to a specific location in a file.
 770  *
 771  * @param fd        Open file handle from smbc_open() or smbc_creat()
 772  *
 773  * @param offset    Offset in bytes from whence
 774  *
 775  * @param whence    A location in the file:
 776  *                  - SEEK_SET The offset is set to offset bytes from
 777  *                  the beginning of the file
 778  *                  - SEEK_CUR The offset is set to current location
 779  *                  plus offset bytes.
 780  *                  - SEEK_END The offset is set to the size of the
 781  *                  file plus offset bytes.
 782  *
 783  * @return          Upon successful completion, lseek returns the
 784  *                  resulting offset location as measured in bytes
 785  *                  from the beginning  of the file. Otherwise, a value
 786  *                  of (off_t)-1 is returned and errno is set to
 787  *                  indicate the error:
 788  *                  - EBADF  Fildes is not an open file descriptor.
 789  *                  - EINVAL Whence is not a proper value or smbc_init
 790  *                    not called.
 791  *
 792  * @todo Are all the whence values really supported?
 793  *
 794  * @todo Are errno values complete and correct?
 795  */
 796 #ifdef __cplusplus
 797 extern "C" {
 798 #endif
 799 off_t smbc_lseek(int fd, off_t offset, int whence);
 800 #ifdef __cplusplus
 801 }
 802 #endif
 803
 804 /**@ingroup file
 805  * Close an open file handle.
 806  *
 807  * @param fd        The file handle to close
 808  *
 809  * @return          0 on success, < 0 on error with errno set:
 810  *                  - EBADF  fd isn't a valid open file descriptor
 811  *                  - EINVAL smbc_init() failed or has not been called
 812  *
 813  * @see             smbc_open(), smbc_creat()
 814  */
 815 #ifdef __cplusplus
 816 extern "C" {
 817 #endif
 818 int smbc_close(int fd);
 819 #ifdef __cplusplus
 820 }
 821 #endif
 822
 823 /**@ingroup directory
 824  * Unlink (delete) a file or directory.
 825  *
 826  * @param furl      The smb url of the file to delete
 827  *
 828  * @return          0 on success, < 0 on error with errno set:
 829  *                  - EACCES or EPERM Write  access  to the directory
 830  *                  containing pathname is not allowed or one
 831  *                  of  the  directories in pathname did not allow
 832  *                  search (execute) permission
 833  *                  - ENOENT A directory component in pathname does
 834  *                  not exist
 835  *                  - EINVAL NULL was passed in the file param or
 836  *                    smbc_init not called.
 837  *                  - EACCES You do not have access to the file
 838  *                  - ENOMEM Insufficient kernel memory was available
 839  *
 840  * @see             smbc_rmdir()s
 841  *
 842  * @todo Are errno values complete and correct?
 843  */
 844 #ifdef __cplusplus
 845 extern "C" {
 846 #endif
 847 int smbc_unlink(const char *furl);
 848 #ifdef __cplusplus
 849 }
 850 #endif
 851
 852 /**@ingroup directory
 853  * Rename or move a file or directory.
 854  *
 855  * @param ourl      The original smb url (source url) of file or
 856  *                  directory to be moved
 857  *
 858  * @param nurl      The new smb url (destination url) of the file
 859  *                  or directory after the move.  Currently nurl must
 860  *                  be on the same share as ourl.
 861  *
 862  * @return          0 on success, < 0 on error with errno set:
 863  *                  - EISDIR nurl is an existing directory, but ourl is
 864  *                  not a directory.
 865  *                  - EEXIST nurl is  a  non-empty directory,
 866  *                  i.e., contains entries other than "." and ".."
 867  *                  - EINVAL The  new  url  contained  a path prefix
 868  *                  of the old, or, more generally, an  attempt was
 869  *                  made  to make a directory a subdirectory of itself
 870  *                  or smbc_init not called.
 871  *                  - ENOTDIR A component used as a directory in ourl
 872  *                  or nurl path is not, in fact, a directory.  Or,
 873  *                  ourl  is a directory, and newpath exists but is not
 874  *                  a directory.
 875  *                  - EACCES or EPERM Write access to the directory
 876  *                  containing ourl or nurl is not allowed for the
 877  *                  process's effective uid,  or  one of the
 878  *                  directories in ourl or nurl did not allow search
 879  *                  (execute) permission,  or ourl  was  a  directory
 880  *                  and did not allow write permission.
 881  *                  - ENOENT A  directory component in ourl or nurl
 882  *                  does not exist.
 883  *                  - EXDEV Rename across shares not supported.
 884  *                  - ENOMEM Insufficient kernel memory was available.
 885  *                  - EEXIST The target file, nurl, already exists.
 886  *
 887  *
 888  * @todo Are we going to support copying when urls are not on the same
 889  *       share?  I say no... NOTE. I agree for the moment.
 890  *
 891  */
 892 #ifdef __cplusplus
 893 extern "C" {
 894 #endif
 895 int smbc_rename(const char *ourl, const char *nurl);
 896 #ifdef __cplusplus
 897 }
 898 #endif
 899
 900 /**@ingroup directory
 901  * Open a directory used to obtain directory entries.
 902  *
 903  * @param durl      The smb url of the directory to open
 904  *
 905  * @return          Valid directory handle. < 0 on error with errno set:
 906  *                  - EACCES Permission denied.
 907  *                  - EINVAL A NULL file/URL was passed, or the URL would
 908  *                  not parse, or was of incorrect form or smbc_init not
 909  *                  called.
 910  *                  - ENOENT durl does not exist, or name is an
 911  *                  - ENOMEM Insufficient memory to complete the
 912  *                  operation.
 913  *                  - ENOTDIR name is not a directory.
 914  *                  - EPERM the workgroup could not be found.
 915  *                  - ENODEV the workgroup or server could not be found.
 916  *
 917  * @see             smbc_getdents(), smbc_readdir(), smbc_closedir()
 918  *
 919  */
 920 #ifdef __cplusplus
 921 extern "C" {
 922 #endif
 923 int smbc_opendir(const char *durl);
 924 #ifdef __cplusplus
 925 }
 926 #endif
 927
 928 /**@ingroup directory
 929  * Close a directory handle opened by smbc_opendir().
 930  *
 931  * @param dh        Directory handle to close
 932  *
 933  * @return          0 on success, < 0 on error with errno set:
 934  *                  - EBADF dh is an invalid directory handle
 935  *
 936  * @see             smbc_opendir()
 937  */
 938 #ifdef __cplusplus
 939 extern "C" {
 940 #endif
 941 int smbc_closedir(int dh);
 942 #ifdef __cplusplus
 943 }
 944 #endif
 945
 946 /**@ingroup directory
 947  * Get multiple directory entries.
 948  *
 949  * smbc_getdents() reads as many dirent structures from the an open
 950  * directory handle into a specified memory area as will fit.
 951  *
 952  * @param dh        Valid directory as returned by smbc_opendir()
 953  *
 954  * @param dirp      pointer to buffer that will receive the directory
 955  *                  entries.
 956  *
 957  * @param count     The size of the dirp buffer in bytes
 958  *
 959  * @returns         If any dirents returned, return will indicate the
 960  *                  total size. If there were no more dirents available,
 961  *                  0 is returned. < 0 indicates an error.
 962  *                  - EBADF  Invalid directory handle
 963  *                  - EINVAL Result buffer is too small or smbc_init
 964  *                  not called.
 965  *                  - ENOENT No such directory.
 966  * @see             , smbc_dirent, smbc_readdir(), smbc_open()
 967  *
 968  * @todo Are errno values complete and correct?
 969  *
 970  * @todo Add example code so people know how to parse buffers.
 971  */
 972 #ifdef __cplusplus
 973 extern "C" {
 974 #endif
 975 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
 976 #ifdef __cplusplus
 977 }
 978 #endif
 979
 980 /**@ingroup directory
 981  * Get a single directory entry.
 982  *
 983  * @param dh        Valid directory as returned by smbc_opendir()
 984  *
 985  * @return          A pointer to a smbc_dirent structure, or NULL if an
 986  *                  error occurs or end-of-directory is reached:
 987  *                  - EBADF Invalid directory handle
 988  *                  - EINVAL smbc_init() failed or has not been called
 989  *
 990  * @see             smbc_dirent, smbc_getdents(), smbc_open()
 991  */
 992 #ifdef __cplusplus
 993 extern "C" {
 994 #endif
 995 struct smbc_dirent* smbc_readdir(unsigned int dh);
 996 #ifdef __cplusplus
 997 }
 998 #endif
 999
1000 /**@ingroup directory
1001  * Get the current directory offset.
1002  *
1003  * smbc_telldir() may be used in conjunction with smbc_readdir() and
1004  * smbc_lseekdir().
1005  *
1006  * @param dh        Valid directory as returned by smbc_opendir()
1007  *
1008  * @return          The current location in the directory stream or -1
1009  *                  if an error occur.  The current location is not
1010  *                  an offset. Becuase of the implementation, it is a
1011  *                  handle that allows the library to find the entry
1012  *                  later.
1013  *                  - EBADF dh is not a valid directory handle
1014  *                  - EINVAL smbc_init() failed or has not been called
1015  *                  - ENOTDIR if dh is not a directory
1016  *
1017  * @see             smbc_readdir()
1018  *
1019  */
1020 #ifdef __cplusplus
1021 extern "C" {
1022 #endif
1023 off_t smbc_telldir(int dh);
1024 #ifdef __cplusplus
1025 }
1026 #endif
1027
1028 /**@ingroup directory
1029  * lseek on directories.
1030  *
1031  * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1032  * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1033  *
1034  * @param fd        Valid directory as returned by smbc_opendir()
1035  *
1036  * @param offset    The offset (as returned by smbc_telldir). Can be
1037  *                  NULL, in which case we will rewind
1038  *
1039  * @return          0 on success, -1 on failure
1040  *                  - EBADF dh is not a valid directory handle
1041  *                  - ENOTDIR if dh is not a directory
1042  *                  - EINVAL offset did not refer to a valid dirent or
1043  *                    smbc_init not called.
1044  *
1045  * @see             smbc_telldir()
1046  *
1047  *
1048  * @todo In what does the reture and errno values mean?
1049  */
1050 #ifdef __cplusplus
1051 extern "C" {
1052 #endif
1053 int smbc_lseekdir(int fd, off_t offset);
1054 #ifdef __cplusplus
1055 }
1056 #endif
1057
1058 /**@ingroup directory
1059  * Create a directory.
1060  *
1061  * @param durl      The url of the directory to create
1062  *
1063  * @param mode      Specifies  the  permissions to use. It is modified
1064  *                  by the process's umask in the usual way: the
1065  *                  permissions of the created file are (mode & ~umask).
1066  *
1067  * @return          0 on success, < 0 on error with errno set:
1068  *                  - EEXIST directory url already exists
1069  *                  - EACCES The parent directory does not allow write
1070  *                  permission to the process, or one of the directories
1071  *                  - ENOENT A directory component in pathname does not
1072  *                  exist.
1073  *                  - EINVAL NULL durl passed or smbc_init not called.
1074  *                  - ENOMEM Insufficient memory was available.
1075  *
1076  * @see             smbc_rmdir()
1077  *
1078  */
1079 #ifdef __cplusplus
1080 extern "C" {
1081 #endif
1082 int smbc_mkdir(const char *durl, mode_t mode);
1083 #ifdef __cplusplus
1084 }
1085 #endif
1086
1087 /**@ingroup directory
1088  * Remove a directory.
1089  *
1090  * @param durl      The smb url of the directory to remove
1091  *
1092  * @return          0 on success, < 0 on error with errno set:
1093  *                  - EACCES or EPERM Write access to the directory
1094  *                  containing pathname was not allowed.
1095  *                  - EINVAL durl is NULL or smbc_init not called.
1096  *                  - ENOENT A directory component in pathname does not
1097  *                  exist.
1098  *                  - ENOTEMPTY directory contains entries.
1099  *                  - ENOMEM Insufficient kernel memory was available.
1100  *
1101  * @see             smbc_mkdir(), smbc_unlink()
1102  *
1103  * @todo Are errno values complete and correct?
1104  */
1105 #ifdef __cplusplus
1106 extern "C" {
1107 #endif
1108 int smbc_rmdir(const char *durl);
1109 #ifdef __cplusplus
1110 }
1111 #endif
1112
1113 /**@ingroup attribute
1114  * Get information about a file or directory.
1115  *
1116  * @param url       The smb url to get information for
1117  *
1118  * @param st        pointer to a buffer that will be filled with
1119  *                  standard Unix struct stat information.
1120  *
1121  * @return          0 on success, < 0 on error with errno set:
1122  *                  - ENOENT A component of the path file_name does not
1123  *                  exist.
1124  *                  - EINVAL a NULL url was passed or smbc_init not called.
1125  *                  - EACCES Permission denied.
1126  *                  - ENOMEM Out of memory
1127  *                  - ENOTDIR The target dir, url, is not a directory.
1128  *
1129  * @see             Unix stat()
1130  *
1131  */
1132 #ifdef __cplusplus
1133 extern "C" {
1134 #endif
1135 int smbc_stat(const char *url, struct stat *st);
1136 #ifdef __cplusplus
1137 }
1138 #endif
1139
1140 /**@ingroup attribute
1141  * Get file information via an file descriptor.
1142  *
1143  * @param fd        Open file handle from smbc_open() or smbc_creat()
1144  *
1145  * @param st        pointer to a buffer that will be filled with
1146  *                  standard Unix struct stat information.
1147  *
1148  * @return          EBADF  filedes is bad.
1149  *                  - EACCES Permission denied.
1150  *                  - EBADF fd is not a valid file descriptor
1151  *                  - EINVAL Problems occurred in the underlying routines
1152  *                    or smbc_init not called.
1153  *                  - ENOMEM Out of memory
1154  *
1155  * @see             smbc_stat(), Unix stat()
1156  *
1157  */
1158 #ifdef __cplusplus
1159 extern "C" {
1160 #endif
1161 int smbc_fstat(int fd, struct stat *st);
1162 #ifdef __cplusplus
1163 }
1164 #endif
1165
1166 /**@ingroup attribue
1167  * Change the ownership of a file or directory.
1168  *
1169  * @param url       The smb url of the file or directory to change
1170  *                  ownership of.
1171  *
1172  * @param owner     I have no idea?
1173  *
1174  * @param group     I have not idea?
1175  *
1176  * @return          0 on success, < 0 on error with errno set:
1177  *                  - EPERM  The effective UID does not match the owner
1178  *                  of the file, and is not zero; or the owner or group
1179  *                  were specified incorrectly.
1180  *                  - ENOENT The file does not exist.
1181  *                  - ENOMEM Insufficient was available.
1182  *                  - ENOENT file or directory does not exist
1183  *
1184  * @todo Are we actually going to be able to implement this function
1185  *
1186  * @todo How do we abstract owner and group uid and gid?
1187  *
1188  */
1189 #ifdef __cplusplus
1190 extern "C" {
1191 #endif
1192 int smbc_chown(const char *url, uid_t owner, gid_t group);
1193 #ifdef __cplusplus
1194 }
1195 #endif
1196
1197 /**@ingroup attribute
1198  * Change the permissions of a file.
1199  *
1200  * @param url       The smb url of the file or directory to change
1201  *                  permissions of
1202  *
1203  * @param mode      The permissions to set:
1204  *                  - Put good explaination of permissions here!
1205  *
1206  * @return          0 on success, < 0 on error with errno set:
1207  *                  - EPERM  The effective UID does not match the owner
1208  *                  of the file, and is not zero
1209  *                  - ENOENT The file does not exist.
1210  *                  - ENOMEM Insufficient was available.
1211  *                  - ENOENT file or directory does not exist
1212  *
1213  * @todo Actually implement this fuction?
1214  *
1215  * @todo Are errno values complete and correct?
1216  */
1217 #ifdef __cplusplus
1218 extern "C" {
1219 #endif
1220 int smbc_chmod(const char *url, mode_t mode);
1221 #ifdef __cplusplus
1222 }
1223 #endif
1224
1225 /**@ingroup attribute
1226  * Change the last modification time on a file
1227  *
1228  * @param url       The smb url of the file or directory to change
1229  *                  the modification time of
1230  *
1231  * @param tbuf      A timeval structure which contains the desired
1232  *                  modification time.  NOTE: Only the tv_sec field is
1233  *                  used.  The tv_usec (microseconds) portion is ignored.
1234  *
1235  * @return          0 on success, < 0 on error with errno set:
1236  *                  - EINVAL The client library is not properly initialized
1237  *                  - EPERM  Permission was denied.
1238  *
1239  */
1240 #ifdef __cplusplus
1241 extern "C" {
1242 #endif
1243 int smbc_utimes(const char *url, struct timeval *tbuf);
1244 #ifdef __cplusplus
1245 }
1246 #endif
1247
1248 #ifdef HAVE_UTIME_H
1249 /**@ingroup attribute
1250  * Change the last modification time on a file
1251  *
1252  * @param url       The smb url of the file or directory to change
1253  *                  the modification time of
1254  *
1255  * @param utbuf     A utimebuf structure which contains the desired
1256  *                  modification time.  NOTE: Although the structure contains
1257  *                  an access time as well, the access time value is ignored.
1258  *
1259  * @return          0 on success, < 0 on error with errno set:
1260  *                  - EINVAL The client library is not properly initialized
1261  *                  - ENOMEM No memory was available for internal needs
1262  *                  - EPERM  Permission was denied.
1263  *
1264  */
1265 #ifdef __cplusplus
1266 extern "C" {
1267 #endif
1268 int smbc_utime(const char *fname, struct utimbuf *utbuf);
1269 #ifdef __cplusplus
1270 }
1271 #endif
1272 #endif
1273
1274 /**@ingroup attribute
1275  * Set extended attributes for a file.  This is used for modifying a file's
1276  * security descriptor (i.e. owner, group, and access control list)
1277  *
1278  * @param url       The smb url of the file or directory to set extended
1279  *                  attributes for.
1280  *
1281  * @param name      The name of an attribute to be changed.  Names are of
1282  *                  one of the following forms:
1283  *
1284  *                     system.nt_sec_desc.<attribute name>
1285  *                     system.nt_sec_desc.*
1286  *                     system.nt_sec_desc.*+
1287  *
1288  *                  where <attribute name> is one of:
1289  *
1290  *                     revision
1291  *                     owner
1292  *                     owner+
1293  *                     group
1294  *                     group+
1295  *                     acl:<name or sid>
1296  *                     acl+:<name or sid>
1297  *
1298  *                  In the forms "system.nt_sec_desc.*" and
1299  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1300  *                  literal, i.e. the string is provided exactly as shown, and
1301  *                  the value parameter should contain a complete security
1302  *                  descriptor with name:value pairs separated by tabs,
1303  *                  commas, or newlines (not spaces!).
1304  *
1305  *                  The plus sign ('+') indicates that SIDs should be mapped
1306  *                  to names.  Without the plus sign, SIDs are not mapped;
1307  *                  rather they are simply converted to a string format.
1308  *
1309  * @param value     The value to be assigned to the specified attribute name.
1310  *                  This buffer should contain only the attribute value if the
1311  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1312  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1313  *                  then a complete security descriptor, with name:value pairs
1314  *                  separated by tabs, commas, or newlines (not spaces!),
1315  *                  should be provided in this value buffer.  A complete
1316  *                  security descriptor will contain one or more entries
1317  *                  selected from the following:
1318  *
1319  *                    REVISION:<revision number>
1320  *                    OWNER:<sid or name>
1321  *                    GROUP:<sid or name>
1322  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1323  *
1324  *                  The  revision of the ACL specifies the internal Windows NT
1325  *                  ACL revision for the security descriptor. If not specified
1326  *                  it defaults to  1.  Using values other than 1 may cause
1327  *                  strange behaviour.
1328  *
1329  *                  The owner and group specify the owner and group sids for
1330  *                  the object. If the attribute name (either '*+' with a
1331  *                  complete security descriptor, or individual 'owner+' or
1332  *                  'group+' attribute names) ended with a plus sign, the
1333  *                  specified name is resolved to a SID value, using the
1334  *                  server on which the file or directory resides.  Otherwise,
1335  *                  the value should be provided in SID-printable format as
1336  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1337  *                  associated with the ACL: attribute should be provided
1338  *                  similarly.
1339  *
1340  * @param size      The number of the bytes of data in the value buffer
1341  *
1342  * @param flags     A bit-wise OR of zero or more of the following:
1343  *                    SMBC_XATTR_FLAG_CREATE -
1344  *                      fail if the named attribute already exists
1345  *                    SMBC_XATTR_FLAG_REPLACE -
1346  *                      fail if the attribute does not already exist
1347  *
1348  *                  If neither flag is specified, the specified attributes
1349  *                  will be added or replace existing attributes of the same
1350  *                  name, as necessary.
1351  *
1352  * @return          0 on success, < 0 on error with errno set:
1353  *                  - EINVAL  The client library is not properly initialized
1354  *                            or one of the parameters is not of a correct
1355  *                            form
1356  *                  - ENOMEM No memory was available for internal needs
1357  *                  - EEXIST  If the attribute already exists and the flag
1358  *                            SMBC_XATTR_FLAG_CREAT was specified
1359  *                  - ENOATTR If the attribute does not exist and the flag
1360  *                            SMBC_XATTR_FLAG_REPLACE was specified
1361  *                  - EPERM   Permission was denied.
1362  *                  - ENOTSUP The referenced file system does not support
1363  *                            extended attributes
1364  *
1365  * @note            Attribute names are compared in a case-insensitive
1366  *                  fashion.  All of the following are equivalent, although
1367  *                  the all-lower-case name is the preferred format:
1368  *                    system.nt_sec_desc.owner
1369  *                    SYSTEM.NT_SEC_DESC.OWNER
1370  *                    sYsTeM.nt_sEc_desc.owNER
1371  *
1372  */
1373 #ifdef __cplusplus
1374 extern "C" {
1375 #endif
1376 int smbc_setxattr(const char *url,
1377                   const char *name,
1378                   const void *value,
1379                   size_t size,
1380                   int flags);
1381 #ifdef __cplusplus
1382 }
1383 #endif
1384
1385 /**@ingroup attribute
1386  * Set extended attributes for a file.  This is used for modifying a file's
1387  * security descriptor (i.e. owner, group, and access control list).  The
1388  * POSIX function which this maps to would act on a symbolic link rather than
1389  * acting on what the symbolic link points to, but with no symbolic links in
1390  * SMB file systems, this function is functionally identical to
1391  * smbc_setxattr().
1392  *
1393  * @param url       The smb url of the file or directory to set extended
1394  *                  attributes for.
1395  *
1396  * @param name      The name of an attribute to be changed.  Names are of
1397  *                  one of the following forms:
1398  *
1399  *                     system.nt_sec_desc.<attribute name>
1400  *                     system.nt_sec_desc.*
1401  *                     system.nt_sec_desc.*+
1402  *
1403  *                  where <attribute name> is one of:
1404  *
1405  *                     revision
1406  *                     owner
1407  *                     owner+
1408  *                     group
1409  *                     group+
1410  *                     acl:<name or sid>
1411  *                     acl+:<name or sid>
1412  *
1413  *                  In the forms "system.nt_sec_desc.*" and
1414  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1415  *                  literal, i.e. the string is provided exactly as shown, and
1416  *                  the value parameter should contain a complete security
1417  *                  descriptor with name:value pairs separated by tabs,
1418  *                  commas, or newlines (not spaces!).
1419  *
1420  *                  The plus sign ('+') indicates that SIDs should be mapped
1421  *                  to names.  Without the plus sign, SIDs are not mapped;
1422  *                  rather they are simply converted to a string format.
1423  *
1424  * @param value     The value to be assigned to the specified attribute name.
1425  *                  This buffer should contain only the attribute value if the
1426  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1427  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1428  *                  then a complete security descriptor, with name:value pairs
1429  *                  separated by tabs, commas, or newlines (not spaces!),
1430  *                  should be provided in this value buffer.  A complete
1431  *                  security descriptor will contain one or more entries
1432  *                  selected from the following:
1433  *
1434  *                    REVISION:<revision number>
1435  *                    OWNER:<sid or name>
1436  *                    GROUP:<sid or name>
1437  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1438  *
1439  *                  The  revision of the ACL specifies the internal Windows NT
1440  *                  ACL revision for the security descriptor. If not specified
1441  *                  it defaults to  1.  Using values other than 1 may cause
1442  *                  strange behaviour.
1443  *
1444  *                  The owner and group specify the owner and group sids for
1445  *                  the object. If the attribute name (either '*+' with a
1446  *                  complete security descriptor, or individual 'owner+' or
1447  *                  'group+' attribute names) ended with a plus sign, the
1448  *                  specified name is resolved to a SID value, using the
1449  *                  server on which the file or directory resides.  Otherwise,
1450  *                  the value should be provided in SID-printable format as
1451  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1452  *                  associated with the ACL: attribute should be provided
1453  *                  similarly.
1454  *
1455  * @param size      The number of the bytes of data in the value buffer
1456  *
1457  * @param flags     A bit-wise OR of zero or more of the following:
1458  *                    SMBC_XATTR_FLAG_CREATE -
1459  *                      fail if the named attribute already exists
1460  *                    SMBC_XATTR_FLAG_REPLACE -
1461  *                      fail if the attribute does not already exist
1462  *
1463  *                  If neither flag is specified, the specified attributes
1464  *                  will be added or replace existing attributes of the same
1465  *                  name, as necessary.
1466  *
1467  * @return          0 on success, < 0 on error with errno set:
1468  *                  - EINVAL  The client library is not properly initialized
1469  *                            or one of the parameters is not of a correct
1470  *                            form
1471  *                  - ENOMEM No memory was available for internal needs
1472  *                  - EEXIST  If the attribute already exists and the flag
1473  *                            SMBC_XATTR_FLAG_CREAT was specified
1474  *                  - ENOATTR If the attribute does not exist and the flag
1475  *                            SMBC_XATTR_FLAG_REPLACE was specified
1476  *                  - EPERM   Permission was denied.
1477  *                  - ENOTSUP The referenced file system does not support
1478  *                            extended attributes
1479  *
1480  * @note            Attribute names are compared in a case-insensitive
1481  *                  fashion.  All of the following are equivalent, although
1482  *                  the all-lower-case name is the preferred format:
1483  *                    system.nt_sec_desc.owner
1484  *                    SYSTEM.NT_SEC_DESC.OWNER
1485  *                    sYsTeM.nt_sEc_desc.owNER
1486  *
1487  */
1488 #ifdef __cplusplus
1489 extern "C" {
1490 #endif
1491 int smbc_lsetxattr(const char *url,
1492                    const char *name,
1493                    const void *value,
1494                    size_t size,
1495                    int flags);
1496 #ifdef __cplusplus
1497 }
1498 #endif
1499
1500 /**@ingroup attribute
1501  * Set extended attributes for a file.  This is used for modifying a file's
1502  * security descriptor (i.e. owner, group, and access control list)
1503  *
1504  * @param fd        A file descriptor associated with an open file (as
1505  *                  previously returned by smbc_open(), to get extended
1506  *                  attributes for.
1507  *
1508  * @param name      The name of an attribute to be changed.  Names are of
1509  *                  one of the following forms:
1510  *
1511  *                     system.nt_sec_desc.<attribute name>
1512  *                     system.nt_sec_desc.*
1513  *                     system.nt_sec_desc.*+
1514  *
1515  *                  where <attribute name> is one of:
1516  *
1517  *                     revision
1518  *                     owner
1519  *                     owner+
1520  *                     group
1521  *                     group+
1522  *                     acl:<name or sid>
1523  *                     acl+:<name or sid>
1524  *
1525  *                  In the forms "system.nt_sec_desc.*" and
1526  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1527  *                  literal, i.e. the string is provided exactly as shown, and
1528  *                  the value parameter should contain a complete security
1529  *                  descriptor with name:value pairs separated by tabs,
1530  *                  commas, or newlines (not spaces!).
1531  *
1532  *                  The plus sign ('+') indicates that SIDs should be mapped
1533  *                  to names.  Without the plus sign, SIDs are not mapped;
1534  *                  rather they are simply converted to a string format.
1535  *
1536  * @param value     The value to be assigned to the specified attribute name.
1537  *                  This buffer should contain only the attribute value if the
1538  *                  name was of the "system.nt_sec_desc.<attribute_name>"
1539  *                  form.  If the name was of the "system.nt_sec_desc.*" form
1540  *                  then a complete security descriptor, with name:value pairs
1541  *                  separated by tabs, commas, or newlines (not spaces!),
1542  *                  should be provided in this value buffer.  A complete
1543  *                  security descriptor will contain one or more entries
1544  *                  selected from the following:
1545  *
1546  *                    REVISION:<revision number>
1547  *                    OWNER:<sid or name>
1548  *                    GROUP:<sid or name>
1549  *                    ACL:<sid or name>:<type>/<flags>/<mask>
1550  *
1551  *                  The  revision of the ACL specifies the internal Windows NT
1552  *                  ACL revision for the security descriptor. If not specified
1553  *                  it defaults to  1.  Using values other than 1 may cause
1554  *                  strange behaviour.
1555  *
1556  *                  The owner and group specify the owner and group sids for
1557  *                  the object. If the attribute name (either '*+' with a
1558  *                  complete security descriptor, or individual 'owner+' or
1559  *                  'group+' attribute names) ended with a plus sign, the
1560  *                  specified name is resolved to a SID value, using the
1561  *                  server on which the file or directory resides.  Otherwise,
1562  *                  the value should be provided in SID-printable format as
1563  *                  S-1-x-y-z, and is used directly.  The <sid or name>
1564  *                  associated with the ACL: attribute should be provided
1565  *                  similarly.
1566  *
1567  * @param size      The number of the bytes of data in the value buffer
1568  *
1569  * @param flags     A bit-wise OR of zero or more of the following:
1570  *                    SMBC_XATTR_FLAG_CREATE -
1571  *                      fail if the named attribute already exists
1572  *                    SMBC_XATTR_FLAG_REPLACE -
1573  *                      fail if the attribute does not already exist
1574  *
1575  *                  If neither flag is specified, the specified attributes
1576  *                  will be added or replace existing attributes of the same
1577  *                  name, as necessary.
1578  *
1579  * @return          0 on success, < 0 on error with errno set:
1580  *                  - EINVAL  The client library is not properly initialized
1581  *                            or one of the parameters is not of a correct
1582  *                            form
1583  *                  - ENOMEM No memory was available for internal needs
1584  *                  - EEXIST  If the attribute already exists and the flag
1585  *                            SMBC_XATTR_FLAG_CREAT was specified
1586  *                  - ENOATTR If the attribute does not exist and the flag
1587  *                            SMBC_XATTR_FLAG_REPLACE was specified
1588  *                  - EPERM   Permission was denied.
1589  *                  - ENOTSUP The referenced file system does not support
1590  *                            extended attributes
1591  *
1592  * @note            Attribute names are compared in a case-insensitive
1593  *                  fashion.  All of the following are equivalent, although
1594  *                  the all-lower-case name is the preferred format:
1595  *                    system.nt_sec_desc.owner
1596  *                    SYSTEM.NT_SEC_DESC.OWNER
1597  *                    sYsTeM.nt_sEc_desc.owNER
1598  *
1599  */
1600 #ifdef __cplusplus
1601 extern "C" {
1602 #endif
1603 int smbc_fsetxattr(int fd,
1604                    const char *name,
1605                    const void *value,
1606                    size_t size,
1607                    int flags);
1608 #ifdef __cplusplus
1609 }
1610 #endif
1611
1612 /**@ingroup attribute
1613  * Get extended attributes for a file.
1614  *
1615  * @param url       The smb url of the file or directory to get extended
1616  *                  attributes for.
1617  *
1618  * @param name      The name of an attribute to be retrieved.  Names are of
1619  *                  one of the following forms:
1620  *
1621  *                     system.nt_sec_desc.<attribute name>
1622  *                     system.nt_sec_desc.*
1623  *                     system.nt_sec_desc.*+
1624  *
1625  *                  where <attribute name> is one of:
1626  *
1627  *                     revision
1628  *                     owner
1629  *                     owner+
1630  *                     group
1631  *                     group+
1632  *                     acl:<name or sid>
1633  *                     acl+:<name or sid>
1634  *
1635  *                  In the forms "system.nt_sec_desc.*" and
1636  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1637  *                  literal, i.e. the string is provided exactly as shown, and
1638  *                  the value parameter will return a complete security
1639  *                  descriptor with name:value pairs separated by tabs,
1640  *                  commas, or newlines (not spaces!).
1641  *
1642  *                  The plus sign ('+') indicates that SIDs should be mapped
1643  *                  to names.  Without the plus sign, SIDs are not mapped;
1644  *                  rather they are simply converted to a string format.
1645  *
1646  * @param value     A pointer to a buffer in which the value of the specified
1647  *                  attribute will be placed (unless size is zero).
1648  *
1649  * @param size      The size of the buffer pointed to by value.  This parameter
1650  *                  may also be zero, in which case the size of the buffer
1651  *                  required to hold the attribute value will be returned,
1652  *                  but nothing will be placed into the value buffer.
1653  *
1654  * @return          0 on success, < 0 on error with errno set:
1655  *                  - EINVAL  The client library is not properly initialized
1656  *                            or one of the parameters is not of a correct
1657  *                            form
1658  *                  - ENOMEM No memory was available for internal needs
1659  *                  - EEXIST  If the attribute already exists and the flag
1660  *                            SMBC_XATTR_FLAG_CREAT was specified
1661  *                  - ENOATTR If the attribute does not exist and the flag
1662  *                            SMBC_XATTR_FLAG_REPLACE was specified
1663  *                  - EPERM   Permission was denied.
1664  *                  - ENOTSUP The referenced file system does not support
1665  *                            extended attributes
1666  *
1667  */
1668 #ifdef __cplusplus
1669 extern "C" {
1670 #endif
1671 int smbc_getxattr(const char *url,
1672                   const char *name,
1673                   const void *value,
1674                   size_t size);
1675 #ifdef __cplusplus
1676 }
1677 #endif
1678
1679 /**@ingroup attribute
1680  * Get extended attributes for a file.  The POSIX function which this maps to
1681  * would act on a symbolic link rather than acting on what the symbolic link
1682  * points to, but with no symbolic links in SMB file systems, this function
1683  * is functionally identical to smbc_getxattr().
1684  *
1685  * @param url       The smb url of the file or directory to get extended
1686  *                  attributes for.
1687  *
1688  * @param name      The name of an attribute to be retrieved.  Names are of
1689  *                  one of the following forms:
1690  *
1691  *                     system.nt_sec_desc.<attribute name>
1692  *                     system.nt_sec_desc.*
1693  *                     system.nt_sec_desc.*+
1694  *
1695  *                  where <attribute name> is one of:
1696  *
1697  *                     revision
1698  *                     owner
1699  *                     owner+
1700  *                     group
1701  *                     group+
1702  *                     acl:<name or sid>
1703  *                     acl+:<name or sid>
1704  *
1705  *                  In the forms "system.nt_sec_desc.*" and
1706  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1707  *                  literal, i.e. the string is provided exactly as shown, and
1708  *                  the value parameter will return a complete security
1709  *                  descriptor with name:value pairs separated by tabs,
1710  *                  commas, or newlines (not spaces!).
1711  *
1712  *                  The plus sign ('+') indicates that SIDs should be mapped
1713  *                  to names.  Without the plus sign, SIDs are not mapped;
1714  *                  rather they are simply converted to a string format.
1715  *
1716  * @param value     A pointer to a buffer in which the value of the specified
1717  *                  attribute will be placed (unless size is zero).
1718  *
1719  * @param size      The size of the buffer pointed to by value.  This parameter
1720  *                  may also be zero, in which case the size of the buffer
1721  *                  required to hold the attribute value will be returned,
1722  *                  but nothing will be placed into the value buffer.
1723  *
1724  * @return          0 on success, < 0 on error with errno set:
1725  *                  - EINVAL  The client library is not properly initialized
1726  *                            or one of the parameters is not of a correct
1727  *                            form
1728  *                  - ENOMEM No memory was available for internal needs
1729  *                  - EEXIST  If the attribute already exists and the flag
1730  *                            SMBC_XATTR_FLAG_CREAT was specified
1731  *                  - ENOATTR If the attribute does not exist and the flag
1732  *                            SMBC_XATTR_FLAG_REPLACE was specified
1733  *                  - EPERM   Permission was denied.
1734  *                  - ENOTSUP The referenced file system does not support
1735  *                            extended attributes
1736  *
1737  */
1738 #ifdef __cplusplus
1739 extern "C" {
1740 #endif
1741 int smbc_lgetxattr(const char *url,
1742                    const char *name,
1743                    const void *value,
1744                    size_t size);
1745 #ifdef __cplusplus
1746 }
1747 #endif
1748
1749 /**@ingroup attribute
1750  * Get extended attributes for a file.
1751  *
1752  * @param fd        A file descriptor associated with an open file (as
1753  *                  previously returned by smbc_open(), to get extended
1754  *                  attributes for.
1755  *
1756  * @param name      The name of an attribute to be retrieved.  Names are of
1757  *                  one of the following forms:
1758  *
1759  *                     system.nt_sec_desc.<attribute name>
1760  *                     system.nt_sec_desc.*
1761  *                     system.nt_sec_desc.*+
1762  *
1763  *                  where <attribute name> is one of:
1764  *
1765  *                     revision
1766  *                     owner
1767  *                     owner+
1768  *                     group
1769  *                     group+
1770  *                     acl:<name or sid>
1771  *                     acl+:<name or sid>
1772  *
1773  *                  In the forms "system.nt_sec_desc.*" and
1774  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1775  *                  literal, i.e. the string is provided exactly as shown, and
1776  *                  the value parameter will return a complete security
1777  *                  descriptor with name:value pairs separated by tabs,
1778  *                  commas, or newlines (not spaces!).
1779  *
1780  *                  The plus sign ('+') indicates that SIDs should be mapped
1781  *                  to names.  Without the plus sign, SIDs are not mapped;
1782  *                  rather they are simply converted to a string format.
1783  *
1784  * @param value     A pointer to a buffer in which the value of the specified
1785  *                  attribute will be placed (unless size is zero).
1786  *
1787  * @param size      The size of the buffer pointed to by value.  This parameter
1788  *                  may also be zero, in which case the size of the buffer
1789  *                  required to hold the attribute value will be returned,
1790  *                  but nothing will be placed into the value buffer.
1791  *
1792  * @return          0 on success, < 0 on error with errno set:
1793  *                  - EINVAL  The client library is not properly initialized
1794  *                            or one of the parameters is not of a correct
1795  *                            form
1796  *                  - ENOMEM No memory was available for internal needs
1797  *                  - EEXIST  If the attribute already exists and the flag
1798  *                            SMBC_XATTR_FLAG_CREAT was specified
1799  *                  - ENOATTR If the attribute does not exist and the flag
1800  *                            SMBC_XATTR_FLAG_REPLACE was specified
1801  *                  - EPERM   Permission was denied.
1802  *                  - ENOTSUP The referenced file system does not support
1803  *                            extended attributes
1804  *
1805  */
1806 #ifdef __cplusplus
1807 extern "C" {
1808 #endif
1809 int smbc_fgetxattr(int fd,
1810                    const char *name,
1811                    const void *value,
1812                    size_t size);
1813 #ifdef __cplusplus
1814 }
1815 #endif
1816
1817 /**@ingroup attribute
1818  * Remove extended attributes for a file.  This is used for modifying a file's
1819  * security descriptor (i.e. owner, group, and access control list)
1820  *
1821  * @param url       The smb url of the file or directory to remove the extended
1822  *                  attributes for.
1823  *
1824  * @param name      The name of an attribute to be removed.  Names are of
1825  *                  one of the following forms:
1826  *
1827  *                     system.nt_sec_desc.<attribute name>
1828  *                     system.nt_sec_desc.*
1829  *                     system.nt_sec_desc.*+
1830  *
1831  *                  where <attribute name> is one of:
1832  *
1833  *                     revision
1834  *                     owner
1835  *                     owner+
1836  *                     group
1837  *                     group+
1838  *                     acl:<name or sid>
1839  *                     acl+:<name or sid>
1840  *
1841  *                  In the forms "system.nt_sec_desc.*" and
1842  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1843  *                  literal, i.e. the string is provided exactly as shown, and
1844  *                  the value parameter will return a complete security
1845  *                  descriptor with name:value pairs separated by tabs,
1846  *                  commas, or newlines (not spaces!).
1847  *
1848  *                  The plus sign ('+') indicates that SIDs should be mapped
1849  *                  to names.  Without the plus sign, SIDs are not mapped;
1850  *                  rather they are simply converted to a string format.
1851  *
1852  * @return          0 on success, < 0 on error with errno set:
1853  *                  - EINVAL The client library is not properly initialized
1854  *                  - ENOMEM No memory was available for internal needs
1855  *                  - EPERM  Permission was denied.
1856  *                  - ENOTSUP The referenced file system does not support
1857  *                            extended attributes
1858  *
1859  */
1860 #ifdef __cplusplus
1861 extern "C" {
1862 #endif
1863 int smbc_removexattr(const char *url,
1864                      const char *name);
1865 #ifdef __cplusplus
1866 }
1867 #endif
1868
1869 /**@ingroup attribute
1870  * Remove extended attributes for a file.  This is used for modifying a file's
1871  * security descriptor (i.e. owner, group, and access control list) The POSIX
1872  * function which this maps to would act on a symbolic link rather than acting
1873  * on what the symbolic link points to, but with no symbolic links in SMB file
1874  * systems, this function is functionally identical to smbc_removexattr().
1875  *
1876  * @param url       The smb url of the file or directory to remove the extended
1877  *                  attributes for.
1878  *
1879  * @param name      The name of an attribute to be removed.  Names are of
1880  *                  one of the following forms:
1881  *
1882  *                     system.nt_sec_desc.<attribute name>
1883  *                     system.nt_sec_desc.*
1884  *                     system.nt_sec_desc.*+
1885  *
1886  *                  where <attribute name> is one of:
1887  *
1888  *                     revision
1889  *                     owner
1890  *                     owner+
1891  *                     group
1892  *                     group+
1893  *                     acl:<name or sid>
1894  *                     acl+:<name or sid>
1895  *
1896  *                  In the forms "system.nt_sec_desc.*" and
1897  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1898  *                  literal, i.e. the string is provided exactly as shown, and
1899  *                  the value parameter will return a complete security
1900  *                  descriptor with name:value pairs separated by tabs,
1901  *                  commas, or newlines (not spaces!).
1902  *
1903  *                  The plus sign ('+') indicates that SIDs should be mapped
1904  *                  to names.  Without the plus sign, SIDs are not mapped;
1905  *                  rather they are simply converted to a string format.
1906  *
1907  * @return          0 on success, < 0 on error with errno set:
1908  *                  - EINVAL The client library is not properly initialized
1909  *                  - ENOMEM No memory was available for internal needs
1910  *                  - EPERM  Permission was denied.
1911  *                  - ENOTSUP The referenced file system does not support
1912  *                            extended attributes
1913  *
1914  */
1915 #ifdef __cplusplus
1916 extern "C" {
1917 #endif
1918 int smbc_lremovexattr(const char *url,
1919                       const char *name);
1920 #ifdef __cplusplus
1921 }
1922 #endif
1923
1924 /**@ingroup attribute
1925  * Remove extended attributes for a file.  This is used for modifying a file's
1926  * security descriptor (i.e. owner, group, and access control list)
1927  *
1928  * @param fd        A file descriptor associated with an open file (as
1929  *                  previously returned by smbc_open(), to get extended
1930  *                  attributes for.
1931  *
1932  * @param name      The name of an attribute to be removed.  Names are of
1933  *                  one of the following forms:
1934  *
1935  *                     system.nt_sec_desc.<attribute name>
1936  *                     system.nt_sec_desc.*
1937  *                     system.nt_sec_desc.*+
1938  *
1939  *                  where <attribute name> is one of:
1940  *
1941  *                     revision
1942  *                     owner
1943  *                     owner+
1944  *                     group
1945  *                     group+
1946  *                     acl:<name or sid>
1947  *                     acl+:<name or sid>
1948  *
1949  *                  In the forms "system.nt_sec_desc.*" and
1950  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
1951  *                  literal, i.e. the string is provided exactly as shown, and
1952  *                  the value parameter will return a complete security
1953  *                  descriptor with name:value pairs separated by tabs,
1954  *                  commas, or newlines (not spaces!).
1955  *
1956  *                  The plus sign ('+') indicates that SIDs should be mapped
1957  *                  to names.  Without the plus sign, SIDs are not mapped;
1958  *                  rather they are simply converted to a string format.
1959  *
1960  * @return          0 on success, < 0 on error with errno set:
1961  *                  - EINVAL The client library is not properly initialized
1962  *                  - ENOMEM No memory was available for internal needs
1963  *                  - EPERM  Permission was denied.
1964  *                  - ENOTSUP The referenced file system does not support
1965  *                            extended attributes
1966  *
1967  */
1968 #ifdef __cplusplus
1969 extern "C" {
1970 #endif
1971 int smbc_fremovexattr(int fd,
1972                       const char *name);
1973 #ifdef __cplusplus
1974 }
1975 #endif
1976
1977 /**@ingroup attribute
1978  * List the supported extended attribute names associated with a file
1979  *
1980  * @param url       The smb url of the file or directory to list the extended
1981  *                  attributes for.
1982  *
1983  * @param list      A pointer to a buffer in which the list of attributes for
1984  *                  the specified file or directory will be placed (unless
1985  *                  size is zero).
1986  *
1987  * @param size      The size of the buffer pointed to by list.  This parameter
1988  *                  may also be zero, in which case the size of the buffer
1989  *                  required to hold all of the attribute names will be
1990  *                  returned, but nothing will be placed into the list buffer.
1991  *
1992  * @return          0 on success, < 0 on error with errno set:
1993  *                  - EINVAL The client library is not properly initialized
1994  *                  - ENOMEM No memory was available for internal needs
1995  *                  - EPERM  Permission was denied.
1996  *                  - ENOTSUP The referenced file system does not support
1997  *                            extended attributes
1998  *
1999  * @note            This function always returns all attribute names supported
2000  *                  by NT file systems, regardless of wether the referenced
2001  *                  file system supports extended attributes (e.g. a Windows
2002  *                  2000 machine supports extended attributes if NTFS is used,
2003  *                  but not if FAT is used, and Windows 98 doesn't support
2004  *                  extended attributes at all.  Whether this is a feature or
2005  *                  a bug is yet to be decided.
2006  */
2007 #ifdef __cplusplus
2008 extern "C" {
2009 #endif
2010 int smbc_listxattr(const char *url,
2011                    char *list,
2012                    size_t size);
2013 #ifdef __cplusplus
2014 }
2015 #endif
2016
2017 /**@ingroup attribute
2018  * List the supported extended attribute names associated with a file The
2019  * POSIX function which this maps to would act on a symbolic link rather than
2020  * acting on what the symbolic link points to, but with no symbolic links in
2021  * SMB file systems, this function is functionally identical to
2022  * smbc_listxattr().
2023  *
2024  * @param url       The smb url of the file or directory to list the extended
2025  *                  attributes for.
2026  *
2027  * @param list      A pointer to a buffer in which the list of attributes for
2028  *                  the specified file or directory will be placed (unless
2029  *                  size is zero).
2030  *
2031  * @param size      The size of the buffer pointed to by list.  This parameter
2032  *                  may also be zero, in which case the size of the buffer
2033  *                  required to hold all of the attribute names will be
2034  *                  returned, but nothing will be placed into the list buffer.
2035  *
2036  * @return          0 on success, < 0 on error with errno set:
2037  *                  - EINVAL The client library is not properly initialized
2038  *                  - ENOMEM No memory was available for internal needs
2039  *                  - EPERM  Permission was denied.
2040  *                  - ENOTSUP The referenced file system does not support
2041  *                            extended attributes
2042  *
2043  * @note            This function always returns all attribute names supported
2044  *                  by NT file systems, regardless of wether the referenced
2045  *                  file system supports extended attributes (e.g. a Windows
2046  *                  2000 machine supports extended attributes if NTFS is used,
2047  *                  but not if FAT is used, and Windows 98 doesn't support
2048  *                  extended attributes at all.  Whether this is a feature or
2049  *                  a bug is yet to be decided.
2050  */
2051 #ifdef __cplusplus
2052 extern "C" {
2053 #endif
2054 int smbc_llistxattr(const char *url,
2055                     char *list,
2056                     size_t size);
2057 #ifdef __cplusplus
2058 }
2059 #endif
2060
2061 /**@ingroup attribute
2062  * List the supported extended attribute names associated with a file
2063  *
2064  * @param fd        A file descriptor associated with an open file (as
2065  *                  previously returned by smbc_open(), to get extended
2066  *                  attributes for.
2067  *
2068  * @param list      A pointer to a buffer in which the list of attributes for
2069  *                  the specified file or directory will be placed (unless
2070  *                  size is zero).
2071  *
2072  * @param size      The size of the buffer pointed to by list.  This parameter
2073  *                  may also be zero, in which case the size of the buffer
2074  *                  required to hold all of the attribute names will be
2075  *                  returned, but nothing will be placed into the list buffer.
2076  *
2077  * @return          0 on success, < 0 on error with errno set:
2078  *                  - EINVAL The client library is not properly initialized
2079  *                  - ENOMEM No memory was available for internal needs
2080  *                  - EPERM  Permission was denied.
2081  *                  - ENOTSUP The referenced file system does not support
2082  *                            extended attributes
2083  *
2084  * @note            This function always returns all attribute names supported
2085  *                  by NT file systems, regardless of wether the referenced
2086  *                  file system supports extended attributes (e.g. a Windows
2087  *                  2000 machine supports extended attributes if NTFS is used,
2088  *                  but not if FAT is used, and Windows 98 doesn't support
2089  *                  extended attributes at all.  Whether this is a feature or
2090  *                  a bug is yet to be decided.
2091  */
2092 #ifdef __cplusplus
2093 extern "C" {
2094 #endif
2095 int smbc_flistxattr(int fd,
2096                     char *list,
2097                     size_t size);
2098 #ifdef __cplusplus
2099 }
2100 #endif
2101
2102 /**@ingroup print
2103  * Print a file given the name in fname. It would be a URL ...
2104  *
2105  * @param fname     The URL of a file on a remote SMB server that the
2106  *                  caller wants printed
2107  *
2108  * @param printq    The URL of the print share to print the file to.
2109  *
2110  * @return          0 on success, < 0 on error with errno set:
2111  *
2112  *                  - EINVAL fname or printq was NULL or smbc_init not
2113  *                    not called.
2114  *                  and errors returned by smbc_open
2115  *
2116  */
2117 #ifdef __cplusplus
2118 extern "C" {
2119 #endif
2120 int smbc_print_file(const char *fname, const char *printq);
2121 #ifdef __cplusplus
2122 }
2123 #endif
2124
2125 /**@ingroup print
2126  * Open a print file that can be written to by other calls. This simply
2127  * does an smbc_open call after checking if there is a file name on the
2128  * URI. If not, a temporary name is added ...
2129  *
2130  * @param fname     The URL of the print share to print to?
2131  *
2132  * @returns         A file handle for the print file if successful.
2133  *                  Returns -1 if an error ocurred and errno has the values
2134  *                  - EINVAL fname was NULL or smbc_init not called.
2135  *                  - all errors returned by smbc_open
2136  *
2137  */
2138 #ifdef __cplusplus
2139 extern "C" {
2140 #endif
2141 int smbc_open_print_job(const char *fname);
2142 #ifdef __cplusplus
2143 }
2144 #endif
2145
2146 /**@ingroup print
2147  * List the print jobs on a print share, for the moment, pass a callback
2148  *
2149  * @param purl      The url of the print share to list the jobs of
2150  *
2151  * @param fn        Callback function the receives printjob info
2152  *
2153  * @return          0 on success, < 0 on error with errno set:
2154  *                  - EINVAL fname was NULL or smbc_init not called
2155  *                  - EACCES ???
2156  */
2157 #ifdef __cplusplus
2158 extern "C" {
2159 #endif
2160 int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
2161 #ifdef __cplusplus
2162 }
2163 #endif
2164
2165 /**@ingroup print
2166  * Delete a print job
2167  *
2168  * @param purl      Url of the print share
2169  *
2170  * @param id        The id of the job to delete
2171  *
2172  * @return          0 on success, < 0 on error with errno set:
2173  *                  - EINVAL fname was NULL or smbc_init not called
2174  *
2175  * @todo    what errno values are possible here?
2176  */
2177 #ifdef __cplusplus
2178 extern "C" {
2179 #endif
2180 int smbc_unlink_print_job(const char *purl, int id);
2181 #ifdef __cplusplus
2182 }
2183 #endif
2184
2185 /**@ingroup callback
2186  * Remove a server from the cached server list it's unused.
2187  *
2188  * @param context    pointer to smb context
2189  *
2190  * @param srv        pointer to server to remove
2191  *
2192  * @return On success, 0 is returned. 1 is returned if the server could not
2193  *         be removed. Also useable outside libsmbclient.
2194  */
2195 #ifdef __cplusplus
2196 extern "C" {
2197 #endif
2198 int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv);
2199 #ifdef __cplusplus
2200 }
2201 #endif
2202
2203 /**@ingroup directory
2204  * Convert strings of %xx to their single character equivalent.
2205  *
2206  * @param dest      A pointer to a buffer in which the resulting decoded
2207  *                  string should be placed.  This may be a pointer to the
2208  *                  same buffer as src_segment.
2209  *
2210  * @param src       A pointer to the buffer containing the URL to be decoded.
2211  *                  Any %xx sequences herein are converted to their single
2212  *                  character equivalent.  Each 'x' must be a valid hexadecimal
2213  *                  digit, or that % sequence is left undecoded.
2214  *
2215  * @param max_dest_len
2216  *                  The size of the buffer pointed to by dest_segment.
2217  *
2218  * @return          The number of % sequences which could not be converted
2219  *                  due to lack of two following hexadecimal digits.
2220  */
2221 #ifdef __cplusplus
2222 extern "C" {
2223 #endif
2224 int
2225 smbc_urldecode(char *dest, char * src, size_t max_dest_len);
2226 #ifdef __cplusplus
2227 }
2228 #endif
2229
2230
2231 /*
2232  * Convert any characters not specifically allowed in a URL into their %xx
2233  * equivalent.
2234  *
2235  * @param dest      A pointer to a buffer in which the resulting encoded
2236  *                  string should be placed.  Unlike smbc_urldecode(), this
2237  *                  must be a buffer unique from src.
2238  *
2239  * @param src       A pointer to the buffer containing the string to be encoded.
2240  *                  Any character not specifically allowed in a URL is converted
2241  *                  into its hexadecimal value and encoded as %xx.
2242  *
2243  * @param max_dest_len
2244  *                  The size of the buffer pointed to by dest_segment.
2245  *
2246  * @returns         The remaining buffer length.
2247  */
2248 #ifdef __cplusplus
2249 extern "C" {
2250 #endif
2251 int
2252 smbc_urlencode(char * dest, char * src, int max_dest_len);
2253 #ifdef __cplusplus
2254 }
2255 #endif
2256
2257
2258 /**@ingroup directory
2259  * Return the version of the linked Samba code, and thus the version of the
2260  * libsmbclient code.
2261  *
2262  * @return          The version string.
2263  */
2264 #ifdef __cplusplus
2265 extern "C" {
2266 #endif
2267 const char *
2268 smbc_version(void);
2269 #ifdef __cplusplus
2270 }
2271 #endif
2272
2273
2274 #endif /* SMBCLIENT_H_INCLUDED */