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
11 This program is free software; you can redistribute it and/or modify
12 it under the terms of the GNU General Public License as published by
13 the Free Software Foundation; either version 2 of the License, or
14 (at your option) any later version.
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.
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 =====================================================================*/
26 #ifndef SMBCLIENT_H_INCLUDED
27 #define SMBCLIENT_H_INCLUDED
33 /*-------------------------------------------------------------------*/
34 /* The following are special comments to instruct DOXYGEN (automated
37 /** \defgroup libsmbclient
39 /** \defgroup structure Data Structures Type and Constants
40 * \ingroup libsmbclient
41 * Data structures, types, and constants
43 /** \defgroup callback Callback function types
44 * \ingroup libsmbclient
47 /** \defgroup file File Functions
48 * \ingroup libsmbclient
49 * Functions used to access individual file contents
51 /** \defgroup directory Directory Functions
52 * \ingroup libsmbclient
53 * Functions used to access directory entries
55 /** \defgroup attribute Attributes Functions
56 * \ingroup libsmbclient
57 * Functions used to view or change file and directory attributes
59 /** \defgroup print Print Functions
60 * \ingroup libsmbclient
61 * Functions used to access printing functionality
63 /** \defgroup misc Miscellaneous Functions
64 * \ingroup libsmbclient
65 * Functions that don't fit in to other categories
67 /*-------------------------------------------------------------------*/
69 /* Make sure we have the following includes for now ... */
70 #include <sys/types.h>
75 #define SMBC_BASE_FD 10000 /* smallest file descriptor returned */
77 #define SMBC_WORKGROUP 1
79 #define SMBC_FILE_SHARE 3
80 #define SMBC_PRINTER_SHARE 4
81 #define SMBC_COMMS_SHARE 5
82 #define SMBC_IPC_SHARE 6
88 * Structure that represents a directory entry.
103 unsigned int smbc_type;
105 /** Length of this smbc_dirent in bytes
108 /** The length of the comment string in bytes (does not include
111 unsigned int commentlen;
112 /** Points to the null terminated comment string
115 /** The length of the name string in bytes (does not include
118 unsigned int namelen;
119 /** Points to the null terminated name string
125 * Flags for smbc_setxattr()
126 * Specify a bitwise OR of these, or 0 to add or replace as necessary
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 */
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.
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
146 # define ENOATTR ENOENT /* No such attribute */
152 /**@ingroup structure
153 * Structure that represents a print job.
157 struct print_job_info
159 /** numeric ID of the print job
163 /** represents print job priority (lower numbers mean higher priority)
165 unsigned short priority;
167 /** Size of the print job
171 /** Name of the user that owns the print job
175 /** Name of the print job. This will have no name if an anonymous print
176 * file was opened. Ie smb://server/printer
180 /** Time the print job was spooled
184 #endif /* _CLIENT_H */
187 /**@ingroup structure
190 typedef struct _SMBCSRV SMBCSRV;
192 /**@ingroup structure
193 * File or directory handle
195 typedef struct _SMBCFILE SMBCFILE;
197 /**@ingroup structure
198 * File or directory handle
200 typedef struct _SMBCCTX SMBCCTX;
207 * Authentication callback function type.
209 * Type for the the authentication function called by the library to
210 * obtain authentication credentals
212 * @param srv Server being authenticated to
214 * @param shr Share being authenticated to
216 * @param wg Pointer to buffer containing a "hint" for the
217 * workgroup to be authenticated. Should be filled in
218 * with the correct workgroup if the hint is wrong.
220 * @param wglen The size of the workgroup buffer in bytes
222 * @param un Pointer to buffer containing a "hint" for the
223 * user name to be use for authentication. Should be
224 * filled in with the correct workgroup if the hint is
227 * @param unlen The size of the username buffer in bytes
229 * @param pw Pointer to buffer containing to which password
232 * @param pwlen The size of the password buffer in bytes
235 typedef void (*smbc_get_auth_data_fn)(const char *srv,
239 char *pw, int pwlen);
243 * Print job info callback function type.
245 * @param i pointer to print job information structure
248 typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
252 * Check if a server is still good
254 * @param c pointer to smb context
256 * @param srv pointer to server to check
258 * @return 0 when connection is good. 1 on error.
261 typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
264 * Remove a server if unused
266 * @param c pointer to smb context
268 * @param srv pointer to server to remove
270 * @return 0 on success. 1 on failure.
273 typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
277 * Add a server to the cache system
279 * @param c pointer to smb context
281 * @param srv pointer to server to add
283 * @param server server name
285 * @param share share name
287 * @param workgroup workgroup used to connect
289 * @param username username used to connect
291 * @return 0 on success. 1 on failure.
294 typedef int (*smbc_add_cached_srv_fn) (SMBCCTX * c, SMBCSRV *srv,
295 const char * server, const char * share,
296 const char * workgroup, const char * username);
299 * Look up a server in the cache system
301 * @param c pointer to smb context
303 * @param server server name to match
305 * @param share share name to match
307 * @param workgroup workgroup to match
309 * @param username username to match
311 * @return pointer to SMBCSRV on success. NULL on failure.
314 typedef SMBCSRV * (*smbc_get_cached_srv_fn) (SMBCCTX * c, const char * server,
315 const char * share, const char * workgroup,
316 const char * username);
319 * Check if a server is still good
321 * @param c pointer to smb context
323 * @param srv pointer to server to remove
325 * @return 0 when found and removed. 1 on failure.
328 typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
332 * Try to remove all servers from the cache system and disconnect
334 * @param c pointer to smb context
336 * @return 0 when found and removed. 1 on failure.
339 typedef int (*smbc_purge_cached_fn) (SMBCCTX * c);
342 /**@ingroup structure
343 * Structure that contains a client context information
344 * This structure is know as SMBCCTX
351 /** netbios name used for making connections
355 /** workgroup name used for making connections
359 /** username used for making connections
363 /** timeout used for waiting on connections / response data (in milliseconds)
367 /** callable functions for files:
368 * For usage and return values see the smbc_* functions
370 SMBCFILE * (*open) (SMBCCTX *c, const char *fname, int flags, mode_t mode);
371 SMBCFILE * (*creat) (SMBCCTX *c, const char *path, mode_t mode);
372 ssize_t (*read) (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
373 ssize_t (*write) (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
374 int (*unlink) (SMBCCTX *c, const char *fname);
375 int (*rename) (SMBCCTX *ocontext, const char *oname,
376 SMBCCTX *ncontext, const char *nname);
377 off_t (*lseek) (SMBCCTX *c, SMBCFILE * file, off_t offset, int whence);
378 int (*stat) (SMBCCTX *c, const char *fname, struct stat *st);
379 int (*fstat) (SMBCCTX *c, SMBCFILE *file, struct stat *st);
380 int (*close_fn) (SMBCCTX *c, SMBCFILE *file);
382 /** callable functions for dirs
384 SMBCFILE * (*opendir) (SMBCCTX *c, const char *fname);
385 int (*closedir)(SMBCCTX *c, SMBCFILE *dir);
386 struct smbc_dirent * (*readdir)(SMBCCTX *c, SMBCFILE *dir);
387 int (*getdents)(SMBCCTX *c, SMBCFILE *dir,
388 struct smbc_dirent *dirp, int count);
389 int (*mkdir) (SMBCCTX *c, const char *fname, mode_t mode);
390 int (*rmdir) (SMBCCTX *c, const char *fname);
391 off_t (*telldir) (SMBCCTX *c, SMBCFILE *dir);
392 int (*lseekdir)(SMBCCTX *c, SMBCFILE *dir, off_t offset);
393 int (*fstatdir)(SMBCCTX *c, SMBCFILE *dir, struct stat *st);
394 int (*chmod)(SMBCCTX *c, const char *fname, mode_t mode);
395 int (*utimes)(SMBCCTX *c,
396 const char *fname, struct timeval *tbuf);
397 int (*setxattr)(SMBCCTX *context,
403 int (*getxattr)(SMBCCTX *context,
408 int (*removexattr)(SMBCCTX *context,
411 int (*listxattr)(SMBCCTX *context,
416 /** callable functions for printing
418 int (*print_file)(SMBCCTX *c_file, const char *fname,
419 SMBCCTX *c_print, const char *printq);
420 SMBCFILE * (*open_print_job)(SMBCCTX *c, const char *fname);
421 int (*list_print_jobs)(SMBCCTX *c, const char *fname, smbc_list_print_job_fn fn);
422 int (*unlink_print_job)(SMBCCTX *c, const char *fname, int id);
426 * These callbacks _always_ have to be initialized because they will not be checked
427 * at dereference for increased speed.
429 struct _smbc_callbacks {
430 /** authentication function callback: called upon auth requests
432 smbc_get_auth_data_fn auth_fn;
434 /** check if a server is still good
436 smbc_check_server_fn check_server_fn;
438 /** remove a server if unused
440 smbc_remove_unused_server_fn remove_unused_server_fn;
443 * For an example cache system see samba/source/libsmb/libsmb_cache.c
444 * Cache subsystem functions follow.
447 /** server cache addition
449 smbc_add_cached_srv_fn add_cached_srv_fn;
451 /** server cache lookup
453 smbc_get_cached_srv_fn get_cached_srv_fn;
455 /** server cache removal
457 smbc_remove_cached_srv_fn remove_cached_srv_fn;
459 /** server cache purging, try to remove all cached servers (disconnect)
461 smbc_purge_cached_fn purge_cached_fn;
465 /** Space to store private data of the server cache.
467 struct smbc_server_cache * server_cache;
471 /** user options selections that apply to this session
473 struct _smbc_options {
476 * From how many local master browsers should the list of
477 * workgroups be retrieved? It can take up to 12 minutes or
478 * longer after a server becomes a local master browser, for
479 * it to have the entire browse list (the list of
480 * workgroups/domains) from an entire network. Since a client
481 * never knows which local master browser will be found first,
482 * the one which is found first and used to retrieve a browse
483 * list may have an incomplete or empty browse list. By
484 * requesting the browse list from multiple local master
485 * browsers, a more complete list can be generated. For small
486 * networks (few workgroups), it is recommended that this
487 * value be set to 0, causing the browse lists from all found
488 * local master browsers to be retrieved and merged. For
489 * networks with many workgroups, a suitable value for this
490 * variable is probably somewhere around 3. (Default: 3).
492 int browse_max_lmb_count;
495 * There is a difference in the desired return strings from
496 * smbc_readdir() depending upon whether the filenames are to
497 * be displayed to the user, or whether they are to be
498 * appended to the path name passed to smbc_opendir() to call
499 * a further smbc_ function (e.g. open the file with
500 * smbc_open()). In the former case, the filename should be
501 * in "human readable" form. In the latter case, the smbc_
502 * functions expect a URL which must be url-encoded. Those
503 * functions decode the URL. If, for example, smbc_readdir()
504 * returned a file name of "abc%20def.txt", passing a path
505 * with this file name attached to smbc_open() would cause
506 * smbc_open to attempt to open the file "abc def.txt" since
507 * the %20 is decoded into a space.
509 * Set this option to True if the names returned by
510 * smbc_readdir() should be url-encoded such that they can be
511 * passed back to another smbc_ call. Set it to False if the
512 * names returned by smbc_readdir() are to be presented to the
515 * For backwards compatibility, this option defaults to False.
517 int urlencode_readdir_entries;
520 * Some Windows versions appear to have a limit to the number
521 * of concurrent SESSIONs and/or TREE CONNECTions. In
522 * one-shot programs (i.e. the program runs and then quickly
523 * ends, thereby shutting down all connections), it is
524 * probably reasonable to establish a new connection for each
525 * share. In long-running applications, the limitation can be
526 * avoided by using only a single connection to each server,
527 * and issuing a new TREE CONNECT when the share is accessed.
529 int one_share_per_server;
533 * do _NOT_ touch this from your program !
535 struct smbc_internal_data * internal;
538 /* Flags for SMBCCTX->flags */
539 #define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
540 #define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
541 #define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2) /* don't try to do automatic anon login */
544 * Create a new SBMCCTX (a context).
546 * Must be called before the context is passed to smbc_context_init()
548 * @return The given SMBCCTX pointer on success, NULL on error with errno set:
549 * - ENOMEM Out of memory
551 * @see smbc_free_context(), smbc_init_context()
553 * @note Do not forget to smbc_init_context() the returned SMBCCTX pointer !
555 SMBCCTX * smbc_new_context(void);
558 * Delete a SBMCCTX (a context) acquired from smbc_new_context().
560 * The context will be deleted if possible.
562 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
564 * @param shutdown_ctx If 1, all connections and files will be closed even if they are busy.
567 * @return Returns 0 on succes. Returns 1 on failure with errno set:
568 * - EBUSY Server connections are still used, Files are open or cache
569 * could not be purged
570 * - EBADF context == NULL
572 * @see smbc_new_context()
574 * @note It is advised to clean up all the contexts with shutdown_ctx set to 1
575 * just before exit()'ing. When shutdown_ctx is 0, this function can be
576 * use in periodical cleanup functions for example.
578 int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
582 * Initialize a SBMCCTX (a context).
584 * Must be called before using any SMBCCTX API function
586 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
588 * @return A pointer to the given SMBCCTX on success, NULL on error with errno set:
589 * - EBADF NULL context given
590 * - ENOMEM Out of memory
591 * - ENOENT The smb.conf file would not load
593 * @see smbc_new_context()
595 * @note my_context = smbc_init_context(smbc_new_context()) is perfectly safe,
596 * but it might leak memory on smbc_context_init() failure. Avoid this.
597 * You'll have to call smbc_free_context() yourself on failure.
600 SMBCCTX * smbc_init_context(SMBCCTX * context);
603 * Initialize the samba client library.
605 * Must be called before using any of the smbclient API function
607 * @param fn The function that will be called to obtaion
608 * authentication credentials.
610 * @param debug Allows caller to set the debug level. Can be
611 * changed in smb.conf file. Allows caller to set
612 * debugging if no smb.conf.
614 * @return 0 on success, < 0 on error with errno set:
615 * - ENOMEM Out of memory
616 * - ENOENT The smb.conf file would not load
620 int smbc_init(smbc_get_auth_data_fn fn, int debug);
623 * Set or retrieve the compatibility library's context pointer
625 * @param context New context to use, or NULL. If a new context is provided,
626 * it must have allocated with smbc_new_context() and
627 * initialized with smbc_init_context(), followed, optionally,
628 * by some manual changes to some of the non-internal fields.
630 * @return The old context.
632 * @see smbc_new_context(), smbc_init_context(), smbc_init()
634 * @note This function may be called prior to smbc_init() to force
635 * use of the next context without any internal calls to
636 * smbc_new_context() or smbc_init_context(). It may also
637 * be called after smbc_init() has already called those two
638 * functions, to replace the existing context with a new one.
639 * Care should be taken, in this latter case, to ensure that
640 * the server cache and any data allocated by the
641 * authentication functions have been freed, if necessary.
644 SMBCCTX * smbc_set_context(SMBCCTX * new_context);
647 * Open a file on an SMB server.
649 * @param furl The smb url of the file to be opened.
651 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
652 * request opening the file read-only,write-only
653 * or read/write. flags may also be bitwise-or'd with
654 * one or more of the following:
655 * O_CREAT - If the file does not exist it will be
657 * O_EXCL - When used with O_CREAT, if the file
658 * already exists it is an error and the open will
660 * O_TRUNC - If the file already exists it will be
662 * O_APPEND The file is opened in append mode
664 * @param mode mode specifies the permissions to use if a new
665 * file is created. It is modified by the
666 * process's umask in the usual way: the permissions
667 * of the created file are (mode & ~umask)
669 * Not currently use, but there for future use.
670 * We will map this to SYSTEM, HIDDEN, etc bits
671 * that reverses the mapping that smbc_fstat does.
673 * @return Valid file handle, < 0 on error with errno set:
674 * - ENOMEM Out of memory
675 * - EINVAL if an invalid parameter passed, like no
676 * file, or smbc_init not called.
677 * - EEXIST pathname already exists and O_CREAT and
679 * - EISDIR pathname refers to a directory and
680 * the access requested involved writing.
681 * - EACCES The requested access to the file is not
683 * - ENODEV The requested share does not exist
684 * - ENOTDIR A file on the path is not a directory
685 * - ENOENT A directory component in pathname does
690 * @note This call uses an underlying routine that may create
691 * a new connection to the server specified in the URL.
692 * If the credentials supplied in the URL, or via the
693 * auth_fn in the smbc_init call, fail, this call will
694 * try again with an empty username and password. This
695 * often gets mapped to the guest account on some machines.
698 int smbc_open(const char *furl, int flags, mode_t mode);
701 * Create a file on an SMB server.
703 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
705 * @param furl The smb url of the file to be created
707 * @param mode mode specifies the permissions to use if a new
708 * file is created. It is modified by the
709 * process's umask in the usual way: the permissions
710 * of the created file are (mode & ~umask)
712 * NOTE, the above is not true. We are dealing with
713 * an SMB server, which has no concept of a umask!
715 * @return Valid file handle, < 0 on error with errno set:
716 * - ENOMEM Out of memory
717 * - EINVAL if an invalid parameter passed, like no
718 * file, or smbc_init not called.
719 * - EEXIST pathname already exists and O_CREAT and
721 * - EISDIR pathname refers to a directory and
722 * the access requested involved writing.
723 * - EACCES The requested access to the file is not
725 * - ENOENT A directory component in pathname does
727 * - ENODEV The requested share does not exist.
732 int smbc_creat(const char *furl, mode_t mode);
735 * Read from a file using an opened file handle.
737 * @param fd Open file handle from smbc_open() or smbc_creat()
739 * @param buf Pointer to buffer to recieve read data
741 * @param bufsize Size of buf in bytes
743 * @return Number of bytes read, < 0 on error with errno set:
744 * - EISDIR fd refers to a directory
745 * - EBADF fd is not a valid file descriptor or
746 * is not open for reading.
747 * - EINVAL fd is attached to an object which is
748 * unsuitable for reading, or no buffer passed or
749 * smbc_init not called.
751 * @see smbc_open(), smbc_write()
754 ssize_t smbc_read(int fd, void *buf, size_t bufsize);
758 * Write to a file using an opened file handle.
760 * @param fd Open file handle from smbc_open() or smbc_creat()
762 * @param buf Pointer to buffer to recieve read data
764 * @param bufsize Size of buf in bytes
766 * @return Number of bytes written, < 0 on error with errno set:
767 * - EISDIR fd refers to a directory.
768 * - EBADF fd is not a valid file descriptor or
769 * is not open for reading.
770 * - EINVAL fd is attached to an object which is
771 * unsuitable for reading, or no buffer passed or
772 * smbc_init not called.
774 * @see smbc_open(), smbc_read()
777 ssize_t smbc_write(int fd, void *buf, size_t bufsize);
781 * Seek to a specific location in a file.
783 * @param fd Open file handle from smbc_open() or smbc_creat()
785 * @param offset Offset in bytes from whence
787 * @param whence A location in the file:
788 * - SEEK_SET The offset is set to offset bytes from
789 * the beginning of the file
790 * - SEEK_CUR The offset is set to current location
792 * - SEEK_END The offset is set to the size of the
793 * file plus offset bytes.
795 * @return Upon successful completion, lseek returns the
796 * resulting offset location as measured in bytes
797 * from the beginning of the file. Otherwise, a value
798 * of (off_t)-1 is returned and errno is set to
799 * indicate the error:
800 * - EBADF Fildes is not an open file descriptor.
801 * - EINVAL Whence is not a proper value or smbc_init
804 * @todo Are all the whence values really supported?
806 * @todo Are errno values complete and correct?
808 off_t smbc_lseek(int fd, off_t offset, int whence);
812 * Close an open file handle.
814 * @param fd The file handle to close
816 * @return 0 on success, < 0 on error with errno set:
817 * - EBADF fd isn't a valid open file descriptor
818 * - EINVAL smbc_init() failed or has not been called
820 * @see smbc_open(), smbc_creat()
822 int smbc_close(int fd);
825 /**@ingroup directory
826 * Unlink (delete) a file or directory.
828 * @param furl The smb url of the file to delete
830 * @return 0 on success, < 0 on error with errno set:
831 * - EACCES or EPERM Write access to the directory
832 * containing pathname is not allowed or one
833 * of the directories in pathname did not allow
834 * search (execute) permission
835 * - ENOENT A directory component in pathname does
837 * - EINVAL NULL was passed in the file param or
838 * smbc_init not called.
839 * - EACCES You do not have access to the file
840 * - ENOMEM Insufficient kernel memory was available
844 * @todo Are errno values complete and correct?
846 int smbc_unlink(const char *furl);
849 /**@ingroup directory
850 * Rename or move a file or directory.
852 * @param ourl The original smb url (source url) of file or
853 * directory to be moved
855 * @param nurl The new smb url (destination url) of the file
856 * or directory after the move. Currently nurl must
857 * be on the same share as ourl.
859 * @return 0 on success, < 0 on error with errno set:
860 * - EISDIR nurl is an existing directory, but ourl is
862 * - EEXIST nurl is a non-empty directory,
863 * i.e., contains entries other than "." and ".."
864 * - EINVAL The new url contained a path prefix
865 * of the old, or, more generally, an attempt was
866 * made to make a directory a subdirectory of itself
867 * or smbc_init not called.
868 * - ENOTDIR A component used as a directory in ourl
869 * or nurl path is not, in fact, a directory. Or,
870 * ourl is a directory, and newpath exists but is not
872 * - EACCES or EPERM Write access to the directory
873 * containing ourl or nurl is not allowed for the
874 * process's effective uid, or one of the
875 * directories in ourl or nurl did not allow search
876 * (execute) permission, or ourl was a directory
877 * and did not allow write permission.
878 * - ENOENT A directory component in ourl or nurl
880 * - EXDEV Rename across shares not supported.
881 * - ENOMEM Insufficient kernel memory was available.
882 * - EEXIST The target file, nurl, already exists.
885 * @todo Are we going to support copying when urls are not on the same
886 * share? I say no... NOTE. I agree for the moment.
889 int smbc_rename(const char *ourl, const char *nurl);
892 /**@ingroup directory
893 * Open a directory used to obtain directory entries.
895 * @param durl The smb url of the directory to open
897 * @return Valid directory handle. < 0 on error with errno set:
898 * - EACCES Permission denied.
899 * - EINVAL A NULL file/URL was passed, or the URL would
900 * not parse, or was of incorrect form or smbc_init not
902 * - ENOENT durl does not exist, or name is an
903 * - ENOMEM Insufficient memory to complete the
905 * - ENOTDIR name is not a directory.
906 * - EPERM the workgroup could not be found.
907 * - ENODEV the workgroup or server could not be found.
909 * @see smbc_getdents(), smbc_readdir(), smbc_closedir()
912 int smbc_opendir(const char *durl);
915 /**@ingroup directory
916 * Close a directory handle opened by smbc_opendir().
918 * @param dh Directory handle to close
920 * @return 0 on success, < 0 on error with errno set:
921 * - EBADF dh is an invalid directory handle
923 * @see smbc_opendir()
925 int smbc_closedir(int dh);
928 /**@ingroup directory
929 * Get multiple directory entries.
931 * smbc_getdents() reads as many dirent structures from the an open
932 * directory handle into a specified memory area as will fit.
934 * @param dh Valid directory as returned by smbc_opendir()
936 * @param dirp pointer to buffer that will receive the directory
939 * @param count The size of the dirp buffer in bytes
941 * @returns If any dirents returned, return will indicate the
942 * total size. If there were no more dirents available,
943 * 0 is returned. < 0 indicates an error.
944 * - EBADF Invalid directory handle
945 * - EINVAL Result buffer is too small or smbc_init
947 * - ENOENT No such directory.
948 * @see , smbc_dirent, smbc_readdir(), smbc_open()
950 * @todo Are errno values complete and correct?
952 * @todo Add example code so people know how to parse buffers.
954 int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
957 /**@ingroup directory
958 * Get a single directory entry.
960 * @param dh Valid directory as returned by smbc_opendir()
962 * @return A pointer to a smbc_dirent structure, or NULL if an
963 * error occurs or end-of-directory is reached:
964 * - EBADF Invalid directory handle
965 * - EINVAL smbc_init() failed or has not been called
967 * @see smbc_dirent, smbc_getdents(), smbc_open()
969 struct smbc_dirent* smbc_readdir(unsigned int dh);
972 /**@ingroup directory
973 * Get the current directory offset.
975 * smbc_telldir() may be used in conjunction with smbc_readdir() and
978 * @param dh Valid directory as returned by smbc_opendir()
980 * @return The current location in the directory stream or -1
981 * if an error occur. The current location is not
982 * an offset. Becuase of the implementation, it is a
983 * handle that allows the library to find the entry
985 * - EBADF dh is not a valid directory handle
986 * - EINVAL smbc_init() failed or has not been called
987 * - ENOTDIR if dh is not a directory
989 * @see smbc_readdir()
992 off_t smbc_telldir(int dh);
995 /**@ingroup directory
996 * lseek on directories.
998 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
999 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1001 * @param fd Valid directory as returned by smbc_opendir()
1003 * @param offset The offset (as returned by smbc_telldir). Can be
1004 * NULL, in which case we will rewind
1006 * @return 0 on success, -1 on failure
1007 * - EBADF dh is not a valid directory handle
1008 * - ENOTDIR if dh is not a directory
1009 * - EINVAL offset did not refer to a valid dirent or
1010 * smbc_init not called.
1012 * @see smbc_telldir()
1015 * @todo In what does the reture and errno values mean?
1017 int smbc_lseekdir(int fd, off_t offset);
1019 /**@ingroup directory
1020 * Create a directory.
1022 * @param durl The url of the directory to create
1024 * @param mode Specifies the permissions to use. It is modified
1025 * by the process's umask in the usual way: the
1026 * permissions of the created file are (mode & ~umask).
1028 * @return 0 on success, < 0 on error with errno set:
1029 * - EEXIST directory url already exists
1030 * - EACCES The parent directory does not allow write
1031 * permission to the process, or one of the directories
1032 * - ENOENT A directory component in pathname does not
1034 * - EINVAL NULL durl passed or smbc_init not called.
1035 * - ENOMEM Insufficient memory was available.
1040 int smbc_mkdir(const char *durl, mode_t mode);
1043 /**@ingroup directory
1044 * Remove a directory.
1046 * @param durl The smb url of the directory to remove
1048 * @return 0 on success, < 0 on error with errno set:
1049 * - EACCES or EPERM Write access to the directory
1050 * containing pathname was not allowed.
1051 * - EINVAL durl is NULL or smbc_init not called.
1052 * - ENOENT A directory component in pathname does not
1054 * - ENOTEMPTY directory contains entries.
1055 * - ENOMEM Insufficient kernel memory was available.
1057 * @see smbc_mkdir(), smbc_unlink()
1059 * @todo Are errno values complete and correct?
1061 int smbc_rmdir(const char *durl);
1064 /**@ingroup attribute
1065 * Get information about a file or directory.
1067 * @param url The smb url to get information for
1069 * @param st pointer to a buffer that will be filled with
1070 * standard Unix struct stat information.
1072 * @return 0 on success, < 0 on error with errno set:
1073 * - ENOENT A component of the path file_name does not
1075 * - EINVAL a NULL url was passed or smbc_init not called.
1076 * - EACCES Permission denied.
1077 * - ENOMEM Out of memory
1078 * - ENOTDIR The target dir, url, is not a directory.
1083 int smbc_stat(const char *url, struct stat *st);
1086 /**@ingroup attribute
1087 * Get file information via an file descriptor.
1089 * @param fd Open file handle from smbc_open() or smbc_creat()
1091 * @param st pointer to a buffer that will be filled with
1092 * standard Unix struct stat information.
1094 * @return EBADF filedes is bad.
1095 * - EACCES Permission denied.
1096 * - EBADF fd is not a valid file descriptor
1097 * - EINVAL Problems occurred in the underlying routines
1098 * or smbc_init not called.
1099 * - ENOMEM Out of memory
1101 * @see smbc_stat(), Unix stat()
1104 int smbc_fstat(int fd, struct stat *st);
1107 /**@ingroup attribue
1108 * Change the ownership of a file or directory.
1110 * @param url The smb url of the file or directory to change
1113 * @param owner I have no idea?
1115 * @param group I have not idea?
1117 * @return 0 on success, < 0 on error with errno set:
1118 * - EPERM The effective UID does not match the owner
1119 * of the file, and is not zero; or the owner or group
1120 * were specified incorrectly.
1121 * - ENOENT The file does not exist.
1122 * - ENOMEM Insufficient was available.
1123 * - ENOENT file or directory does not exist
1125 * @todo Are we actually going to be able to implement this function
1127 * @todo How do we abstract owner and group uid and gid?
1130 int smbc_chown(const char *url, uid_t owner, gid_t group);
1133 /**@ingroup attribute
1134 * Change the permissions of a file.
1136 * @param url The smb url of the file or directory to change
1139 * @param mode The permissions to set:
1140 * - Put good explaination of permissions here!
1142 * @return 0 on success, < 0 on error with errno set:
1143 * - EPERM The effective UID does not match the owner
1144 * of the file, and is not zero
1145 * - ENOENT The file does not exist.
1146 * - ENOMEM Insufficient was available.
1147 * - ENOENT file or directory does not exist
1149 * @todo Actually implement this fuction?
1151 * @todo Are errno values complete and correct?
1153 int smbc_chmod(const char *url, mode_t mode);
1155 /**@ingroup attribute
1156 * Change the last modification time on a file
1158 * @param url The smb url of the file or directory to change
1159 * the modification time of
1161 * @param tbuf A timeval structure which contains the desired
1162 * modification time. NOTE: Only the tv_sec field is
1163 * used. The tv_usec (microseconds) portion is ignored.
1165 * @return 0 on success, < 0 on error with errno set:
1166 * - EINVAL The client library is not properly initialized
1167 * - EPERM Permission was denied.
1170 int smbc_utimes(const char *url, struct timeval *tbuf);
1173 /**@ingroup attribute
1174 * Change the last modification time on a file
1176 * @param url The smb url of the file or directory to change
1177 * the modification time of
1179 * @param utbuf A utimebuf structure which contains the desired
1180 * modification time. NOTE: Although the structure contains
1181 * an access time as well, the access time value is ignored.
1183 * @return 0 on success, < 0 on error with errno set:
1184 * - EINVAL The client library is not properly initialized
1185 * - ENOMEM No memory was available for internal needs
1186 * - EPERM Permission was denied.
1189 int smbc_utime(const char *fname, struct utimbuf *utbuf);
1192 /**@ingroup attribute
1193 * Set extended attributes for a file. This is used for modifying a file's
1194 * security descriptor (i.e. owner, group, and access control list)
1196 * @param url The smb url of the file or directory to set extended
1199 * @param name The name of an attribute to be changed. Names are of
1200 * one of the following forms:
1202 * system.nt_sec_desc.<attribute name>
1203 * system.nt_sec_desc.*
1204 * system.nt_sec_desc.*+
1206 * where <attribute name> is one of:
1214 * acl+:<name or sid>
1216 * In the forms "system.nt_sec_desc.*" and
1217 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1218 * literal, i.e. the string is provided exactly as shown, and
1219 * the value parameter should contain a complete security
1220 * descriptor with name:value pairs separated by tabs,
1221 * commas, or newlines (not spaces!).
1223 * The plus sign ('+') indicates that SIDs should be mapped
1224 * to names. Without the plus sign, SIDs are not mapped;
1225 * rather they are simply converted to a string format.
1227 * @param value The value to be assigned to the specified attribute name.
1228 * This buffer should contain only the attribute value if the
1229 * name was of the "system.nt_sec_desc.<attribute_name>"
1230 * form. If the name was of the "system.nt_sec_desc.*" form
1231 * then a complete security descriptor, with name:value pairs
1232 * separated by tabs, commas, or newlines (not spaces!),
1233 * should be provided in this value buffer. A complete
1234 * security descriptor will contain one or more entries
1235 * selected from the following:
1237 * REVISION:<revision number>
1238 * OWNER:<sid or name>
1239 * GROUP:<sid or name>
1240 * ACL:<sid or name>:<type>/<flags>/<mask>
1242 * The revision of the ACL specifies the internal Windows NT
1243 * ACL revision for the security descriptor. If not specified
1244 * it defaults to 1. Using values other than 1 may cause
1245 * strange behaviour.
1247 * The owner and group specify the owner and group sids for
1248 * the object. If the attribute name (either '*+' with a
1249 * complete security descriptor, or individual 'owner+' or
1250 * 'group+' attribute names) ended with a plus sign, the
1251 * specified name is resolved to a SID value, using the
1252 * server on which the file or directory resides. Otherwise,
1253 * the value should be provided in SID-printable format as
1254 * S-1-x-y-z, and is used directly. The <sid or name>
1255 * associated with the ACL: attribute should be provided
1258 * @param size The number of the bytes of data in the value buffer
1260 * @param flags A bit-wise OR of zero or more of the following:
1261 * SMBC_XATTR_FLAG_CREATE -
1262 * fail if the named attribute already exists
1263 * SMBC_XATTR_FLAG_REPLACE -
1264 * fail if the attribute does not already exist
1266 * If neither flag is specified, the specified attributes
1267 * will be added or replace existing attributes of the same
1268 * name, as necessary.
1270 * @return 0 on success, < 0 on error with errno set:
1271 * - EINVAL The client library is not properly initialized
1272 * or one of the parameters is not of a correct
1274 * - ENOMEM No memory was available for internal needs
1275 * - EEXIST If the attribute already exists and the flag
1276 * SMBC_XATTR_FLAG_CREAT was specified
1277 * - ENOATTR If the attribute does not exist and the flag
1278 * SMBC_XATTR_FLAG_REPLACE was specified
1279 * - EPERM Permission was denied.
1280 * - ENOTSUP The referenced file system does not support
1281 * extended attributes
1283 * @note Attribute names are compared in a case-insensitive
1284 * fashion. All of the following are equivalent, although
1285 * the all-lower-case name is the preferred format:
1286 * system.nt_sec_desc.owner
1287 * SYSTEM.NT_SEC_DESC.OWNER
1288 * sYsTeM.nt_sEc_desc.owNER
1291 int smbc_setxattr(const char *url,
1298 /**@ingroup attribute
1299 * Set extended attributes for a file. This is used for modifying a file's
1300 * security descriptor (i.e. owner, group, and access control list). The
1301 * POSIX function which this maps to would act on a symbolic link rather than
1302 * acting on what the symbolic link points to, but with no symbolic links in
1303 * SMB file systems, this function is functionally identical to
1306 * @param url The smb url of the file or directory to set extended
1309 * @param name The name of an attribute to be changed. Names are of
1310 * one of the following forms:
1312 * system.nt_sec_desc.<attribute name>
1313 * system.nt_sec_desc.*
1314 * system.nt_sec_desc.*+
1316 * where <attribute name> is one of:
1324 * acl+:<name or sid>
1326 * In the forms "system.nt_sec_desc.*" and
1327 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1328 * literal, i.e. the string is provided exactly as shown, and
1329 * the value parameter should contain a complete security
1330 * descriptor with name:value pairs separated by tabs,
1331 * commas, or newlines (not spaces!).
1333 * The plus sign ('+') indicates that SIDs should be mapped
1334 * to names. Without the plus sign, SIDs are not mapped;
1335 * rather they are simply converted to a string format.
1337 * @param value The value to be assigned to the specified attribute name.
1338 * This buffer should contain only the attribute value if the
1339 * name was of the "system.nt_sec_desc.<attribute_name>"
1340 * form. If the name was of the "system.nt_sec_desc.*" form
1341 * then a complete security descriptor, with name:value pairs
1342 * separated by tabs, commas, or newlines (not spaces!),
1343 * should be provided in this value buffer. A complete
1344 * security descriptor will contain one or more entries
1345 * selected from the following:
1347 * REVISION:<revision number>
1348 * OWNER:<sid or name>
1349 * GROUP:<sid or name>
1350 * ACL:<sid or name>:<type>/<flags>/<mask>
1352 * The revision of the ACL specifies the internal Windows NT
1353 * ACL revision for the security descriptor. If not specified
1354 * it defaults to 1. Using values other than 1 may cause
1355 * strange behaviour.
1357 * The owner and group specify the owner and group sids for
1358 * the object. If the attribute name (either '*+' with a
1359 * complete security descriptor, or individual 'owner+' or
1360 * 'group+' attribute names) ended with a plus sign, the
1361 * specified name is resolved to a SID value, using the
1362 * server on which the file or directory resides. Otherwise,
1363 * the value should be provided in SID-printable format as
1364 * S-1-x-y-z, and is used directly. The <sid or name>
1365 * associated with the ACL: attribute should be provided
1368 * @param size The number of the bytes of data in the value buffer
1370 * @param flags A bit-wise OR of zero or more of the following:
1371 * SMBC_XATTR_FLAG_CREATE -
1372 * fail if the named attribute already exists
1373 * SMBC_XATTR_FLAG_REPLACE -
1374 * fail if the attribute does not already exist
1376 * If neither flag is specified, the specified attributes
1377 * will be added or replace existing attributes of the same
1378 * name, as necessary.
1380 * @return 0 on success, < 0 on error with errno set:
1381 * - EINVAL The client library is not properly initialized
1382 * or one of the parameters is not of a correct
1384 * - ENOMEM No memory was available for internal needs
1385 * - EEXIST If the attribute already exists and the flag
1386 * SMBC_XATTR_FLAG_CREAT was specified
1387 * - ENOATTR If the attribute does not exist and the flag
1388 * SMBC_XATTR_FLAG_REPLACE was specified
1389 * - EPERM Permission was denied.
1390 * - ENOTSUP The referenced file system does not support
1391 * extended attributes
1393 * @note Attribute names are compared in a case-insensitive
1394 * fashion. All of the following are equivalent, although
1395 * the all-lower-case name is the preferred format:
1396 * system.nt_sec_desc.owner
1397 * SYSTEM.NT_SEC_DESC.OWNER
1398 * sYsTeM.nt_sEc_desc.owNER
1401 int smbc_lsetxattr(const char *url,
1408 /**@ingroup attribute
1409 * Set extended attributes for a file. This is used for modifying a file's
1410 * security descriptor (i.e. owner, group, and access control list)
1412 * @param fd A file descriptor associated with an open file (as
1413 * previously returned by smbc_open(), to get extended
1416 * @param name The name of an attribute to be changed. Names are of
1417 * one of the following forms:
1419 * system.nt_sec_desc.<attribute name>
1420 * system.nt_sec_desc.*
1421 * system.nt_sec_desc.*+
1423 * where <attribute name> is one of:
1431 * acl+:<name or sid>
1433 * In the forms "system.nt_sec_desc.*" and
1434 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1435 * literal, i.e. the string is provided exactly as shown, and
1436 * the value parameter should contain a complete security
1437 * descriptor with name:value pairs separated by tabs,
1438 * commas, or newlines (not spaces!).
1440 * The plus sign ('+') indicates that SIDs should be mapped
1441 * to names. Without the plus sign, SIDs are not mapped;
1442 * rather they are simply converted to a string format.
1444 * @param value The value to be assigned to the specified attribute name.
1445 * This buffer should contain only the attribute value if the
1446 * name was of the "system.nt_sec_desc.<attribute_name>"
1447 * form. If the name was of the "system.nt_sec_desc.*" form
1448 * then a complete security descriptor, with name:value pairs
1449 * separated by tabs, commas, or newlines (not spaces!),
1450 * should be provided in this value buffer. A complete
1451 * security descriptor will contain one or more entries
1452 * selected from the following:
1454 * REVISION:<revision number>
1455 * OWNER:<sid or name>
1456 * GROUP:<sid or name>
1457 * ACL:<sid or name>:<type>/<flags>/<mask>
1459 * The revision of the ACL specifies the internal Windows NT
1460 * ACL revision for the security descriptor. If not specified
1461 * it defaults to 1. Using values other than 1 may cause
1462 * strange behaviour.
1464 * The owner and group specify the owner and group sids for
1465 * the object. If the attribute name (either '*+' with a
1466 * complete security descriptor, or individual 'owner+' or
1467 * 'group+' attribute names) ended with a plus sign, the
1468 * specified name is resolved to a SID value, using the
1469 * server on which the file or directory resides. Otherwise,
1470 * the value should be provided in SID-printable format as
1471 * S-1-x-y-z, and is used directly. The <sid or name>
1472 * associated with the ACL: attribute should be provided
1475 * @param size The number of the bytes of data in the value buffer
1477 * @param flags A bit-wise OR of zero or more of the following:
1478 * SMBC_XATTR_FLAG_CREATE -
1479 * fail if the named attribute already exists
1480 * SMBC_XATTR_FLAG_REPLACE -
1481 * fail if the attribute does not already exist
1483 * If neither flag is specified, the specified attributes
1484 * will be added or replace existing attributes of the same
1485 * name, as necessary.
1487 * @return 0 on success, < 0 on error with errno set:
1488 * - EINVAL The client library is not properly initialized
1489 * or one of the parameters is not of a correct
1491 * - ENOMEM No memory was available for internal needs
1492 * - EEXIST If the attribute already exists and the flag
1493 * SMBC_XATTR_FLAG_CREAT was specified
1494 * - ENOATTR If the attribute does not exist and the flag
1495 * SMBC_XATTR_FLAG_REPLACE was specified
1496 * - EPERM Permission was denied.
1497 * - ENOTSUP The referenced file system does not support
1498 * extended attributes
1500 * @note Attribute names are compared in a case-insensitive
1501 * fashion. All of the following are equivalent, although
1502 * the all-lower-case name is the preferred format:
1503 * system.nt_sec_desc.owner
1504 * SYSTEM.NT_SEC_DESC.OWNER
1505 * sYsTeM.nt_sEc_desc.owNER
1508 int smbc_fsetxattr(int fd,
1515 /**@ingroup attribute
1516 * Get extended attributes for a file.
1518 * @param url The smb url of the file or directory to get extended
1521 * @param name The name of an attribute to be retrieved. Names are of
1522 * one of the following forms:
1524 * system.nt_sec_desc.<attribute name>
1525 * system.nt_sec_desc.*
1526 * system.nt_sec_desc.*+
1528 * where <attribute name> is one of:
1536 * acl+:<name or sid>
1538 * In the forms "system.nt_sec_desc.*" and
1539 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1540 * literal, i.e. the string is provided exactly as shown, and
1541 * the value parameter will return a complete security
1542 * descriptor with name:value pairs separated by tabs,
1543 * commas, or newlines (not spaces!).
1545 * The plus sign ('+') indicates that SIDs should be mapped
1546 * to names. Without the plus sign, SIDs are not mapped;
1547 * rather they are simply converted to a string format.
1549 * @param value A pointer to a buffer in which the value of the specified
1550 * attribute will be placed (unless size is zero).
1552 * @param size The size of the buffer pointed to by value. This parameter
1553 * may also be zero, in which case the size of the buffer
1554 * required to hold the attribute value will be returned,
1555 * but nothing will be placed into the value buffer.
1557 * @return 0 on success, < 0 on error with errno set:
1558 * - EINVAL The client library is not properly initialized
1559 * or one of the parameters is not of a correct
1561 * - ENOMEM No memory was available for internal needs
1562 * - EEXIST If the attribute already exists and the flag
1563 * SMBC_XATTR_FLAG_CREAT was specified
1564 * - ENOATTR If the attribute does not exist and the flag
1565 * SMBC_XATTR_FLAG_REPLACE was specified
1566 * - EPERM Permission was denied.
1567 * - ENOTSUP The referenced file system does not support
1568 * extended attributes
1571 int smbc_getxattr(const char *url,
1577 /**@ingroup attribute
1578 * Get extended attributes for a file. The POSIX function which this maps to
1579 * would act on a symbolic link rather than acting on what the symbolic link
1580 * points to, but with no symbolic links in SMB file systems, this function
1581 * is functionally identical to smbc_getxattr().
1583 * @param url The smb url of the file or directory to get extended
1586 * @param name The name of an attribute to be retrieved. Names are of
1587 * one of the following forms:
1589 * system.nt_sec_desc.<attribute name>
1590 * system.nt_sec_desc.*
1591 * system.nt_sec_desc.*+
1593 * where <attribute name> is one of:
1601 * acl+:<name or sid>
1603 * In the forms "system.nt_sec_desc.*" and
1604 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1605 * literal, i.e. the string is provided exactly as shown, and
1606 * the value parameter will return a complete security
1607 * descriptor with name:value pairs separated by tabs,
1608 * commas, or newlines (not spaces!).
1610 * The plus sign ('+') indicates that SIDs should be mapped
1611 * to names. Without the plus sign, SIDs are not mapped;
1612 * rather they are simply converted to a string format.
1614 * @param value A pointer to a buffer in which the value of the specified
1615 * attribute will be placed (unless size is zero).
1617 * @param size The size of the buffer pointed to by value. This parameter
1618 * may also be zero, in which case the size of the buffer
1619 * required to hold the attribute value will be returned,
1620 * but nothing will be placed into the value buffer.
1622 * @return 0 on success, < 0 on error with errno set:
1623 * - EINVAL The client library is not properly initialized
1624 * or one of the parameters is not of a correct
1626 * - ENOMEM No memory was available for internal needs
1627 * - EEXIST If the attribute already exists and the flag
1628 * SMBC_XATTR_FLAG_CREAT was specified
1629 * - ENOATTR If the attribute does not exist and the flag
1630 * SMBC_XATTR_FLAG_REPLACE was specified
1631 * - EPERM Permission was denied.
1632 * - ENOTSUP The referenced file system does not support
1633 * extended attributes
1636 int smbc_lgetxattr(const char *url,
1642 /**@ingroup attribute
1643 * Get extended attributes for a file.
1645 * @param fd A file descriptor associated with an open file (as
1646 * previously returned by smbc_open(), to get extended
1649 * @param name The name of an attribute to be retrieved. Names are of
1650 * one of the following forms:
1652 * system.nt_sec_desc.<attribute name>
1653 * system.nt_sec_desc.*
1654 * system.nt_sec_desc.*+
1656 * where <attribute name> is one of:
1664 * acl+:<name or sid>
1666 * In the forms "system.nt_sec_desc.*" and
1667 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1668 * literal, i.e. the string is provided exactly as shown, and
1669 * the value parameter will return a complete security
1670 * descriptor with name:value pairs separated by tabs,
1671 * commas, or newlines (not spaces!).
1673 * The plus sign ('+') indicates that SIDs should be mapped
1674 * to names. Without the plus sign, SIDs are not mapped;
1675 * rather they are simply converted to a string format.
1677 * @param value A pointer to a buffer in which the value of the specified
1678 * attribute will be placed (unless size is zero).
1680 * @param size The size of the buffer pointed to by value. This parameter
1681 * may also be zero, in which case the size of the buffer
1682 * required to hold the attribute value will be returned,
1683 * but nothing will be placed into the value buffer.
1685 * @return 0 on success, < 0 on error with errno set:
1686 * - EINVAL The client library is not properly initialized
1687 * or one of the parameters is not of a correct
1689 * - ENOMEM No memory was available for internal needs
1690 * - EEXIST If the attribute already exists and the flag
1691 * SMBC_XATTR_FLAG_CREAT was specified
1692 * - ENOATTR If the attribute does not exist and the flag
1693 * SMBC_XATTR_FLAG_REPLACE was specified
1694 * - EPERM Permission was denied.
1695 * - ENOTSUP The referenced file system does not support
1696 * extended attributes
1699 int smbc_fgetxattr(int fd,
1705 /**@ingroup attribute
1706 * Remove extended attributes for a file. This is used for modifying a file's
1707 * security descriptor (i.e. owner, group, and access control list)
1709 * @param url The smb url of the file or directory to remove the extended
1712 * @param name The name of an attribute to be removed. Names are of
1713 * one of the following forms:
1715 * system.nt_sec_desc.<attribute name>
1716 * system.nt_sec_desc.*
1717 * system.nt_sec_desc.*+
1719 * where <attribute name> is one of:
1727 * acl+:<name or sid>
1729 * In the forms "system.nt_sec_desc.*" and
1730 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1731 * literal, i.e. the string is provided exactly as shown, and
1732 * the value parameter will return a complete security
1733 * descriptor with name:value pairs separated by tabs,
1734 * commas, or newlines (not spaces!).
1736 * The plus sign ('+') indicates that SIDs should be mapped
1737 * to names. Without the plus sign, SIDs are not mapped;
1738 * rather they are simply converted to a string format.
1740 * @return 0 on success, < 0 on error with errno set:
1741 * - EINVAL The client library is not properly initialized
1742 * - ENOMEM No memory was available for internal needs
1743 * - EPERM Permission was denied.
1744 * - ENOTSUP The referenced file system does not support
1745 * extended attributes
1748 int smbc_removexattr(const char *url,
1752 /**@ingroup attribute
1753 * Remove extended attributes for a file. This is used for modifying a file's
1754 * security descriptor (i.e. owner, group, and access control list) The POSIX
1755 * function which this maps to would act on a symbolic link rather than acting
1756 * on what the symbolic link points to, but with no symbolic links in SMB file
1757 * systems, this function is functionally identical to smbc_removexattr().
1759 * @param url The smb url of the file or directory to remove the extended
1762 * @param name The name of an attribute to be removed. Names are of
1763 * one of the following forms:
1765 * system.nt_sec_desc.<attribute name>
1766 * system.nt_sec_desc.*
1767 * system.nt_sec_desc.*+
1769 * where <attribute name> is one of:
1777 * acl+:<name or sid>
1779 * In the forms "system.nt_sec_desc.*" and
1780 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1781 * literal, i.e. the string is provided exactly as shown, and
1782 * the value parameter will return a complete security
1783 * descriptor with name:value pairs separated by tabs,
1784 * commas, or newlines (not spaces!).
1786 * The plus sign ('+') indicates that SIDs should be mapped
1787 * to names. Without the plus sign, SIDs are not mapped;
1788 * rather they are simply converted to a string format.
1790 * @return 0 on success, < 0 on error with errno set:
1791 * - EINVAL The client library is not properly initialized
1792 * - ENOMEM No memory was available for internal needs
1793 * - EPERM Permission was denied.
1794 * - ENOTSUP The referenced file system does not support
1795 * extended attributes
1798 int smbc_lremovexattr(const char *url,
1802 /**@ingroup attribute
1803 * Remove extended attributes for a file. This is used for modifying a file's
1804 * security descriptor (i.e. owner, group, and access control list)
1806 * @param fd A file descriptor associated with an open file (as
1807 * previously returned by smbc_open(), to get extended
1810 * @param name The name of an attribute to be removed. Names are of
1811 * one of the following forms:
1813 * system.nt_sec_desc.<attribute name>
1814 * system.nt_sec_desc.*
1815 * system.nt_sec_desc.*+
1817 * where <attribute name> is one of:
1825 * acl+:<name or sid>
1827 * In the forms "system.nt_sec_desc.*" and
1828 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1829 * literal, i.e. the string is provided exactly as shown, and
1830 * the value parameter will return a complete security
1831 * descriptor with name:value pairs separated by tabs,
1832 * commas, or newlines (not spaces!).
1834 * The plus sign ('+') indicates that SIDs should be mapped
1835 * to names. Without the plus sign, SIDs are not mapped;
1836 * rather they are simply converted to a string format.
1838 * @return 0 on success, < 0 on error with errno set:
1839 * - EINVAL The client library is not properly initialized
1840 * - ENOMEM No memory was available for internal needs
1841 * - EPERM Permission was denied.
1842 * - ENOTSUP The referenced file system does not support
1843 * extended attributes
1846 int smbc_fremovexattr(int fd,
1850 /**@ingroup attribute
1851 * List the supported extended attribute names associated with a file
1853 * @param url The smb url of the file or directory to list the extended
1856 * @param list A pointer to a buffer in which the list of attributes for
1857 * the specified file or directory will be placed (unless
1860 * @param size The size of the buffer pointed to by list. This parameter
1861 * may also be zero, in which case the size of the buffer
1862 * required to hold all of the attribute names will be
1863 * returned, but nothing will be placed into the list buffer.
1865 * @return 0 on success, < 0 on error with errno set:
1866 * - EINVAL The client library is not properly initialized
1867 * - ENOMEM No memory was available for internal needs
1868 * - EPERM Permission was denied.
1869 * - ENOTSUP The referenced file system does not support
1870 * extended attributes
1872 * @note This function always returns all attribute names supported
1873 * by NT file systems, regardless of wether the referenced
1874 * file system supports extended attributes (e.g. a Windows
1875 * 2000 machine supports extended attributes if NTFS is used,
1876 * but not if FAT is used, and Windows 98 doesn't support
1877 * extended attributes at all. Whether this is a feature or
1878 * a bug is yet to be decided.
1880 int smbc_listxattr(const char *url,
1884 /**@ingroup attribute
1885 * List the supported extended attribute names associated with a file The
1886 * POSIX function which this maps to would act on a symbolic link rather than
1887 * acting on what the symbolic link points to, but with no symbolic links in
1888 * SMB file systems, this function is functionally identical to
1891 * @param url The smb url of the file or directory to list the extended
1894 * @param list A pointer to a buffer in which the list of attributes for
1895 * the specified file or directory will be placed (unless
1898 * @param size The size of the buffer pointed to by list. This parameter
1899 * may also be zero, in which case the size of the buffer
1900 * required to hold all of the attribute names will be
1901 * returned, but nothing will be placed into the list buffer.
1903 * @return 0 on success, < 0 on error with errno set:
1904 * - EINVAL The client library is not properly initialized
1905 * - ENOMEM No memory was available for internal needs
1906 * - EPERM Permission was denied.
1907 * - ENOTSUP The referenced file system does not support
1908 * extended attributes
1910 * @note This function always returns all attribute names supported
1911 * by NT file systems, regardless of wether the referenced
1912 * file system supports extended attributes (e.g. a Windows
1913 * 2000 machine supports extended attributes if NTFS is used,
1914 * but not if FAT is used, and Windows 98 doesn't support
1915 * extended attributes at all. Whether this is a feature or
1916 * a bug is yet to be decided.
1918 int smbc_llistxattr(const char *url,
1922 /**@ingroup attribute
1923 * List the supported extended attribute names associated with a file
1925 * @param fd A file descriptor associated with an open file (as
1926 * previously returned by smbc_open(), to get extended
1929 * @param list A pointer to a buffer in which the list of attributes for
1930 * the specified file or directory will be placed (unless
1933 * @param size The size of the buffer pointed to by list. This parameter
1934 * may also be zero, in which case the size of the buffer
1935 * required to hold all of the attribute names will be
1936 * returned, but nothing will be placed into the list buffer.
1938 * @return 0 on success, < 0 on error with errno set:
1939 * - EINVAL The client library is not properly initialized
1940 * - ENOMEM No memory was available for internal needs
1941 * - EPERM Permission was denied.
1942 * - ENOTSUP The referenced file system does not support
1943 * extended attributes
1945 * @note This function always returns all attribute names supported
1946 * by NT file systems, regardless of wether the referenced
1947 * file system supports extended attributes (e.g. a Windows
1948 * 2000 machine supports extended attributes if NTFS is used,
1949 * but not if FAT is used, and Windows 98 doesn't support
1950 * extended attributes at all. Whether this is a feature or
1951 * a bug is yet to be decided.
1953 int smbc_flistxattr(int fd,
1958 * Print a file given the name in fname. It would be a URL ...
1960 * @param fname The URL of a file on a remote SMB server that the
1961 * caller wants printed
1963 * @param printq The URL of the print share to print the file to.
1965 * @return 0 on success, < 0 on error with errno set:
1967 * - EINVAL fname or printq was NULL or smbc_init not
1969 * and errors returned by smbc_open
1972 int smbc_print_file(const char *fname, const char *printq);
1975 * Open a print file that can be written to by other calls. This simply
1976 * does an smbc_open call after checking if there is a file name on the
1977 * URI. If not, a temporary name is added ...
1979 * @param fname The URL of the print share to print to?
1981 * @returns A file handle for the print file if successful.
1982 * Returns -1 if an error ocurred and errno has the values
1983 * - EINVAL fname was NULL or smbc_init not called.
1984 * - all errors returned by smbc_open
1987 int smbc_open_print_job(const char *fname);
1990 * List the print jobs on a print share, for the moment, pass a callback
1992 * @param purl The url of the print share to list the jobs of
1994 * @param fn Callback function the receives printjob info
1996 * @return 0 on success, < 0 on error with errno set:
1997 * - EINVAL fname was NULL or smbc_init not called
2000 int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
2003 * Delete a print job
2005 * @param purl Url of the print share
2007 * @param id The id of the job to delete
2009 * @return 0 on success, < 0 on error with errno set:
2010 * - EINVAL fname was NULL or smbc_init not called
2012 * @todo what errno values are possible here?
2014 int smbc_unlink_print_job(const char *purl, int id);
2016 /**@ingroup callback
2017 * Remove a server from the cached server list it's unused.
2019 * @param context pointer to smb context
2021 * @param srv pointer to server to remove
2023 * @return On success, 0 is returned. 1 is returned if the server could not
2024 * be removed. Also useable outside libsmbclient.
2026 int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv);
2032 /**@ingroup directory
2033 * Convert strings of %xx to their single character equivalent.
2035 * @param dest A pointer to a buffer in which the resulting decoded
2036 * string should be placed. This may be a pointer to the
2037 * same buffer as src_segment.
2039 * @param src A pointer to the buffer containing the URL to be decoded.
2040 * Any %xx sequences herein are converted to their single
2041 * character equivalent. Each 'x' must be a valid hexadecimal
2042 * digit, or that % sequence is left undecoded.
2044 * @param max_dest_len
2045 * The size of the buffer pointed to by dest_segment.
2047 * @return The number of % sequences which could not be converted
2048 * due to lack of two following hexadecimal digits.
2054 smbc_urldecode(char *dest, char * src, size_t max_dest_len);
2061 * Convert any characters not specifically allowed in a URL into their %xx
2064 * @param dest A pointer to a buffer in which the resulting encoded
2065 * string should be placed. Unlike smbc_urldecode(), this
2066 * must be a buffer unique from src.
2068 * @param src A pointer to the buffer containing the string to be encoded.
2069 * Any character not specifically allowed in a URL is converted
2070 * into its hexadecimal value and encoded as %xx.
2072 * @param max_dest_len
2073 * The size of the buffer pointed to by dest_segment.
2075 * @returns The remaining buffer length.
2081 smbc_urlencode(char * dest, char * src, int max_dest_len);
2087 /**@ingroup directory
2088 * Return the version of the linked Samba code, and thus the version of the
2089 * libsmbclient code.
2091 * @return The version string.
2103 #endif /* SMBCLIENT_H_INCLUDED */