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