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
29 /*-------------------------------------------------------------------*/
30 /* The following are special comments to instruct DOXYGEN (automated
33 /** \defgroup libsmbclient
35 /** \defgroup structure Data Structures Type and Constants
36 * \ingroup libsmbclient
37 * Data structures, types, and constants
39 /** \defgroup callback Callback function types
40 * \ingroup libsmbclient
43 /** \defgroup file File Functions
44 * \ingroup libsmbclient
45 * Functions used to access individual file contents
47 /** \defgroup directory Directory Functions
48 * \ingroup libsmbclient
49 * Functions used to access directory entries
51 /** \defgroup attribute Attributes Functions
52 * \ingroup libsmbclient
53 * Functions used to view or change file and directory attributes
55 /** \defgroup print Print Functions
56 * \ingroup libsmbclient
57 * Functions used to access printing functionality
59 /** \defgroup misc Miscellaneous Functions
60 * \ingroup libsmbclient
61 * Functions that don't fit in to other categories
63 /*-------------------------------------------------------------------*/
65 /* Make sure we have the following includes for now ... */
66 #include <sys/types.h>
71 #define SMBC_BASE_FD 10000 /* smallest file descriptor returned */
73 #define SMBC_WORKGROUP 1
75 #define SMBC_FILE_SHARE 3
76 #define SMBC_PRINTER_SHARE 4
77 #define SMBC_COMMS_SHARE 5
78 #define SMBC_IPC_SHARE 6
84 * Structure that represents a directory entry.
99 unsigned int smbc_type
;
101 /** Length of this smbc_dirent in bytes
104 /** The length of the comment string in bytes (includes null
107 unsigned int commentlen
;
108 /** Points to the null terminated comment string
111 /** The length of the name string in bytes (includes null
114 unsigned int namelen
;
115 /** Points to the null terminated name string
121 * Flags for smbc_setxattr()
122 * Specify a bitwise OR of these, or 0 to add or replace as necessary
124 #define SMBC_XATTR_FLAG_CREATE 0x1 /* fail if attr already exists */
125 #define SMBC_XATTR_FLAG_REPLACE 0x2 /* fail if attr does not exist */
129 # define ENOATTR ENOENT /* No such attribute */
135 /**@ingroup structure
136 * Structure that represents a print job.
140 struct print_job_info
142 /** numeric ID of the print job
146 /** represents print job priority (lower numbers mean higher priority)
148 unsigned short priority
;
150 /** Size of the print job
154 /** Name of the user that owns the print job
158 /** Name of the print job. This will have no name if an anonymous print
159 * file was opened. Ie smb://server/printer
163 /** Time the print job was spooled
167 #endif /* _CLIENT_H */
170 /**@ingroup structure
173 typedef struct _SMBCSRV SMBCSRV
;
175 /**@ingroup structure
176 * File or directory handle
178 typedef struct _SMBCFILE SMBCFILE
;
180 /**@ingroup structure
181 * File or directory handle
183 typedef struct _SMBCCTX SMBCCTX
;
190 * Authentication callback function type.
192 * Type for the the authentication function called by the library to
193 * obtain authentication credentals
195 * @param srv Server being authenticated to
197 * @param shr Share being authenticated to
199 * @param wg Pointer to buffer containing a "hint" for the
200 * workgroup to be authenticated. Should be filled in
201 * with the correct workgroup if the hint is wrong.
203 * @param wglen The size of the workgroup buffer in bytes
205 * @param un Pointer to buffer containing a "hint" for the
206 * user name to be use for authentication. Should be
207 * filled in with the correct workgroup if the hint is
210 * @param unlen The size of the username buffer in bytes
212 * @param pw Pointer to buffer containing to which password
215 * @param pwlen The size of the password buffer in bytes
218 typedef void (*smbc_get_auth_data_fn
)(const char *srv
,
222 char *pw
, int pwlen
);
226 * Print job info callback function type.
228 * @param i pointer to print job information structure
231 typedef void (*smbc_list_print_job_fn
)(struct print_job_info
*i
);
235 * Check if a server is still good
237 * @param c pointer to smb context
239 * @param srv pointer to server to check
241 * @return 0 when connection is good. 1 on error.
244 typedef int (*smbc_check_server_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
247 * Remove a server if unused
249 * @param c pointer to smb context
251 * @param srv pointer to server to remove
253 * @return 0 on success. 1 on failure.
256 typedef int (*smbc_remove_unused_server_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
260 * Add a server to the cache system
262 * @param c pointer to smb context
264 * @param srv pointer to server to add
266 * @param server server name
268 * @param share share name
270 * @param workgroup workgroup used to connect
272 * @param username username used to connect
274 * @return 0 on success. 1 on failure.
277 typedef int (*smbc_add_cached_srv_fn
) (SMBCCTX
* c
, SMBCSRV
*srv
,
278 const char * server
, const char * share
,
279 const char * workgroup
, const char * username
);
282 * Look up a server in the cache system
284 * @param c pointer to smb context
286 * @param server server name to match
288 * @param share share name to match
290 * @param workgroup workgroup to match
292 * @param username username to match
294 * @return pointer to SMBCSRV on success. NULL on failure.
297 typedef SMBCSRV
* (*smbc_get_cached_srv_fn
) (SMBCCTX
* c
, const char * server
,
298 const char * share
, const char * workgroup
,
299 const char * username
);
302 * Check if a server is still good
304 * @param c pointer to smb context
306 * @param srv pointer to server to remove
308 * @return 0 when found and removed. 1 on failure.
311 typedef int (*smbc_remove_cached_srv_fn
)(SMBCCTX
* c
, SMBCSRV
*srv
);
315 * Try to remove all servers from the cache system and disconnect
317 * @param c pointer to smb context
319 * @return 0 when found and removed. 1 on failure.
322 typedef int (*smbc_purge_cached_fn
) (SMBCCTX
* c
);
327 /**@ingroup structure
328 * Structure that contains a client context information
329 * This structure is know as SMBCCTX
336 /** netbios name used for making connections
340 /** workgroup name used for making connections
344 /** username used for making connections
348 /** timeout used for waiting on connections / response data (in milliseconds)
352 /** callable functions for files:
353 * For usage and return values see the smbc_* functions
355 SMBCFILE
* (*open
) (SMBCCTX
*c
, const char *fname
, int flags
, mode_t mode
);
356 SMBCFILE
* (*creat
) (SMBCCTX
*c
, const char *path
, mode_t mode
);
357 ssize_t (*read
) (SMBCCTX
*c
, SMBCFILE
*file
, void *buf
, size_t count
);
358 ssize_t (*write
) (SMBCCTX
*c
, SMBCFILE
*file
, void *buf
, size_t count
);
359 int (*unlink
) (SMBCCTX
*c
, const char *fname
);
360 int (*rename
) (SMBCCTX
*ocontext
, const char *oname
,
361 SMBCCTX
*ncontext
, const char *nname
);
362 off_t (*lseek
) (SMBCCTX
*c
, SMBCFILE
* file
, off_t offset
, int whence
);
363 int (*stat
) (SMBCCTX
*c
, const char *fname
, struct stat
*st
);
364 int (*fstat
) (SMBCCTX
*c
, SMBCFILE
*file
, struct stat
*st
);
365 int (*close
) (SMBCCTX
*c
, SMBCFILE
*file
);
367 /** callable functions for dirs
369 SMBCFILE
* (*opendir
) (SMBCCTX
*c
, const char *fname
);
370 int (*closedir
)(SMBCCTX
*c
, SMBCFILE
*dir
);
371 struct smbc_dirent
* (*readdir
)(SMBCCTX
*c
, SMBCFILE
*dir
);
372 int (*getdents
)(SMBCCTX
*c
, SMBCFILE
*dir
,
373 struct smbc_dirent
*dirp
, int count
);
374 int (*mkdir
) (SMBCCTX
*c
, const char *fname
, mode_t mode
);
375 int (*rmdir
) (SMBCCTX
*c
, const char *fname
);
376 off_t (*telldir
) (SMBCCTX
*c
, SMBCFILE
*dir
);
377 int (*lseekdir
)(SMBCCTX
*c
, SMBCFILE
*dir
, off_t offset
);
378 int (*fstatdir
)(SMBCCTX
*c
, SMBCFILE
*dir
, struct stat
*st
);
379 int (*chmod
)(SMBCCTX
*c
, const char *fname
, mode_t mode
);
380 int (*utimes
)(SMBCCTX
*c
,
381 const char *fname
, struct timeval
*tbuf
);
382 int (*setxattr
)(SMBCCTX
*context
,
388 int (*getxattr
)(SMBCCTX
*context
,
393 int (*removexattr
)(SMBCCTX
*context
,
396 int (*listxattr
)(SMBCCTX
*context
,
401 /** callable functions for printing
403 int (*print_file
)(SMBCCTX
*c_file
, const char *fname
,
404 SMBCCTX
*c_print
, const char *printq
);
405 SMBCFILE
* (*open_print_job
)(SMBCCTX
*c
, const char *fname
);
406 int (*list_print_jobs
)(SMBCCTX
*c
, const char *fname
, smbc_list_print_job_fn fn
);
407 int (*unlink_print_job
)(SMBCCTX
*c
, const char *fname
, int id
);
411 * These callbacks _always_ have to be initialized because they will not be checked
412 * at dereference for increased speed.
414 struct _smbc_callbacks
{
415 /** authentication function callback: called upon auth requests
417 smbc_get_auth_data_fn auth_fn
;
419 /** check if a server is still good
421 smbc_check_server_fn check_server_fn
;
423 /** remove a server if unused
425 smbc_remove_unused_server_fn remove_unused_server_fn
;
428 * For an example cache system see samba/source/libsmb/libsmb_cache.c
429 * Cache subsystem functions follow.
432 /** server cache addition
434 smbc_add_cached_srv_fn add_cached_srv_fn
;
436 /** server cache lookup
438 smbc_get_cached_srv_fn get_cached_srv_fn
;
440 /** server cache removal
442 smbc_remove_cached_srv_fn remove_cached_srv_fn
;
444 /** server cache purging, try to remove all cached servers (disconnect)
446 smbc_purge_cached_fn purge_cached_fn
;
450 /** Space to store private data of the server cache.
452 struct smbc_server_cache
* server_cache
;
455 * do _NOT_ touch this from your program !
457 struct smbc_internal_data
* internal
;
463 /* Flags for SMBCCTX->flags */
464 #define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
465 #define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
466 #define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2) /* don't try to do automatic anon login */
469 * Create a new SBMCCTX (a context).
471 * Must be called before the context is passed to smbc_context_init()
473 * @return The given SMBCCTX pointer on success, NULL on error with errno set:
474 * - ENOMEM Out of memory
476 * @see smbc_free_context(), smbc_init_context()
478 * @note Do not forget to smbc_init_context() the returned SMBCCTX pointer !
483 SMBCCTX
* smbc_new_context(void);
489 * Delete a SBMCCTX (a context) acquired from smbc_new_context().
491 * The context will be deleted if possible.
493 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
495 * @param shutdown_ctx If 1, all connections and files will be closed even if they are busy.
498 * @return Returns 0 on succes. Returns 1 on failure with errno set:
499 * - EBUSY Server connections are still used, Files are open or cache
500 * could not be purged
501 * - EBADF context == NULL
503 * @see smbc_new_context()
505 * @note It is advised to clean up all the contexts with shutdown_ctx set to 1
506 * just before exit()'ing. When shutdown_ctx is 0, this function can be
507 * use in periodical cleanup functions for example.
512 int smbc_free_context(SMBCCTX
* context
, int shutdown_ctx
);
518 * Initialize a SBMCCTX (a context).
520 * Must be called before using any SMBCCTX API function
522 * @param context A pointer to a SMBCCTX obtained from smbc_new_context()
524 * @return A pointer to the given SMBCCTX on success, NULL on error with errno set:
525 * - EBADF NULL context given
526 * - ENOMEM Out of memory
527 * - ENOENT The smb.conf file would not load
529 * @see smbc_new_context()
531 * @note my_context = smbc_init_context(smbc_new_context()) is perfectly safe,
532 * but it might leak memory on smbc_context_init() failure. Avoid this.
533 * You'll have to call smbc_free_context() yourself on failure.
538 SMBCCTX
* smbc_init_context(SMBCCTX
* context
);
544 * Initialize the samba client library.
546 * Must be called before using any of the smbclient API function
548 * @param fn The function that will be called to obtaion
549 * authentication credentials.
551 * @param debug Allows caller to set the debug level. Can be
552 * changed in smb.conf file. Allows caller to set
553 * debugging if no smb.conf.
555 * @return 0 on success, < 0 on error with errno set:
556 * - ENOMEM Out of memory
557 * - ENOENT The smb.conf file would not load
564 int smbc_init(smbc_get_auth_data_fn fn
, int debug
);
570 * Set or retrieve the compatibility library's context pointer
572 * @param context New context to use, or NULL. If a new context is provided,
573 * it must have allocated with smbc_new_context() and
574 * initialized with smbc_init_context(), followed, optionally,
575 * by some manual changes to some of the non-internal fields.
577 * @return The old context.
579 * @see smbc_new_context(), smbc_init_context(), smbc_init()
581 * @note This function may be called prior to smbc_init() to force
582 * use of the next context without any internal calls to
583 * smbc_new_context() or smbc_init_context(). It may also
584 * be called after smbc_init() has already called those two
585 * functions, to replace the existing context with a new one.
586 * Care should be taken, in this latter case, to ensure that
587 * the server cache and any data allocated by the
588 * authentication functions have been freed, if necessary.
594 SMBCCTX
* smbc_set_context(SMBCCTX
* new_context
);
600 * Open a file on an SMB server.
602 * @param furl The smb url of the file to be opened.
604 * @param flags Is one of O_RDONLY, O_WRONLY or O_RDWR which
605 * request opening the file read-only,write-only
606 * or read/write. flags may also be bitwise-or'd with
607 * one or more of the following:
608 * O_CREAT - If the file does not exist it will be
610 * O_EXCL - When used with O_CREAT, if the file
611 * already exists it is an error and the open will
613 * O_TRUNC - If the file already exists it will be
615 * O_APPEND The file is opened in append mode
617 * @param mode mode specifies the permissions to use if a new
618 * file is created. It is modified by the
619 * process's umask in the usual way: the permissions
620 * of the created file are (mode & ~umask)
622 * Not currently use, but there for future use.
623 * We will map this to SYSTEM, HIDDEN, etc bits
624 * that reverses the mapping that smbc_fstat does.
626 * @return Valid file handle, < 0 on error with errno set:
627 * - ENOMEM Out of memory
628 * - EINVAL if an invalid parameter passed, like no
629 * file, or smbc_init not called.
630 * - EEXIST pathname already exists and O_CREAT and
632 * - EISDIR pathname refers to a directory and
633 * the access requested involved writing.
634 * - EACCES The requested access to the file is not
636 * - ENODEV The requested share does not exist
637 * - ENOTDIR A file on the path is not a directory
638 * - ENOENT A directory component in pathname does
643 * @note This call uses an underlying routine that may create
644 * a new connection to the server specified in the URL.
645 * If the credentials supplied in the URL, or via the
646 * auth_fn in the smbc_init call, fail, this call will
647 * try again with an empty username and password. This
648 * often gets mapped to the guest account on some machines.
653 int smbc_open(const char *furl
, int flags
, mode_t mode
);
659 * Create a file on an SMB server.
661 * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC
663 * @param furl The smb url of the file to be created
665 * @param mode mode specifies the permissions to use if a new
666 * file is created. It is modified by the
667 * process's umask in the usual way: the permissions
668 * of the created file are (mode & ~umask)
670 * NOTE, the above is not true. We are dealing with
671 * an SMB server, which has no concept of a umask!
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 * - ENOENT A directory component in pathname does
685 * - ENODEV The requested share does not exist.
692 int smbc_creat(const char *furl
, mode_t mode
);
698 * Read from a file using an opened file handle.
700 * @param fd Open file handle from smbc_open() or smbc_creat()
702 * @param buf Pointer to buffer to recieve read data
704 * @param bufsize Size of buf in bytes
706 * @return Number of bytes read, < 0 on error with errno set:
707 * - EISDIR fd refers to a directory
708 * - EBADF fd is not a valid file descriptor or
709 * is not open for reading.
710 * - EINVAL fd is attached to an object which is
711 * unsuitable for reading, or no buffer passed or
712 * smbc_init not called.
714 * @see smbc_open(), smbc_write()
720 ssize_t
smbc_read(int fd
, void *buf
, size_t bufsize
);
726 * Write to a file using an opened file handle.
728 * @param fd Open file handle from smbc_open() or smbc_creat()
730 * @param buf Pointer to buffer to recieve read data
732 * @param bufsize Size of buf in bytes
734 * @return Number of bytes written, < 0 on error with errno set:
735 * - EISDIR fd refers to a directory.
736 * - EBADF fd is not a valid file descriptor or
737 * is not open for reading.
738 * - EINVAL fd is attached to an object which is
739 * unsuitable for reading, or no buffer passed or
740 * smbc_init not called.
742 * @see smbc_open(), smbc_read()
748 ssize_t
smbc_write(int fd
, void *buf
, size_t bufsize
);
754 * Seek to a specific location in a file.
756 * @param fd Open file handle from smbc_open() or smbc_creat()
758 * @param offset Offset in bytes from whence
760 * @param whence A location in the file:
761 * - SEEK_SET The offset is set to offset bytes from
762 * the beginning of the file
763 * - SEEK_CUR The offset is set to current location
765 * - SEEK_END The offset is set to the size of the
766 * file plus offset bytes.
768 * @return Upon successful completion, lseek returns the
769 * resulting offset location as measured in bytes
770 * from the beginning of the file. Otherwise, a value
771 * of (off_t)-1 is returned and errno is set to
772 * indicate the error:
773 * - EBADF Fildes is not an open file descriptor.
774 * - EINVAL Whence is not a proper value or smbc_init
777 * @todo Are all the whence values really supported?
779 * @todo Are errno values complete and correct?
784 off_t
smbc_lseek(int fd
, off_t offset
, int whence
);
790 * Close an open file handle.
792 * @param fd The file handle to close
794 * @return 0 on success, < 0 on error with errno set:
795 * - EBADF fd isn't a valid open file descriptor
796 * - EINVAL smbc_init() failed or has not been called
798 * @see smbc_open(), smbc_creat()
803 int smbc_close(int fd
);
808 /**@ingroup directory
809 * Unlink (delete) a file or directory.
811 * @param furl The smb url of the file to delete
813 * @return 0 on success, < 0 on error with errno set:
814 * - EACCES or EPERM Write access to the directory
815 * containing pathname is not allowed or one
816 * of the directories in pathname did not allow
817 * search (execute) permission
818 * - ENOENT A directory component in pathname does
820 * - EINVAL NULL was passed in the file param or
821 * smbc_init not called.
822 * - EACCES You do not have access to the file
823 * - ENOMEM Insufficient kernel memory was available
827 * @todo Are errno values complete and correct?
832 int smbc_unlink(const char *furl
);
837 /**@ingroup directory
838 * Rename or move a file or directory.
840 * @param ourl The original smb url (source url) of file or
841 * directory to be moved
843 * @param nurl The new smb url (destination url) of the file
844 * or directory after the move. Currently nurl must
845 * be on the same share as ourl.
847 * @return 0 on success, < 0 on error with errno set:
848 * - EISDIR nurl is an existing directory, but ourl is
850 * - EEXIST nurl is a non-empty directory,
851 * i.e., contains entries other than "." and ".."
852 * - EINVAL The new url contained a path prefix
853 * of the old, or, more generally, an attempt was
854 * made to make a directory a subdirectory of itself
855 * or smbc_init not called.
856 * - ENOTDIR A component used as a directory in ourl
857 * or nurl path is not, in fact, a directory. Or,
858 * ourl is a directory, and newpath exists but is not
860 * - EACCES or EPERM Write access to the directory
861 * containing ourl or nurl is not allowed for the
862 * process's effective uid, or one of the
863 * directories in ourl or nurl did not allow search
864 * (execute) permission, or ourl was a directory
865 * and did not allow write permission.
866 * - ENOENT A directory component in ourl or nurl
868 * - EXDEV Rename across shares not supported.
869 * - ENOMEM Insufficient kernel memory was available.
870 * - EEXIST The target file, nurl, already exists.
873 * @todo Are we going to support copying when urls are not on the same
874 * share? I say no... NOTE. I agree for the moment.
880 int smbc_rename(const char *ourl
, const char *nurl
);
885 /**@ingroup directory
886 * Open a directory used to obtain directory entries.
888 * @param durl The smb url of the directory to open
890 * @return Valid directory handle. < 0 on error with errno set:
891 * - EACCES Permission denied.
892 * - EINVAL A NULL file/URL was passed, or the URL would
893 * not parse, or was of incorrect form or smbc_init not
895 * - ENOENT durl does not exist, or name is an
896 * - ENOMEM Insufficient memory to complete the
898 * - ENOTDIR name is not a directory.
899 * - EPERM the workgroup could not be found.
900 * - ENODEV the workgroup or server could not be found.
902 * @see smbc_getdents(), smbc_readdir(), smbc_closedir()
908 int smbc_opendir(const char *durl
);
913 /**@ingroup directory
914 * Close a directory handle opened by smbc_opendir().
916 * @param dh Directory handle to close
918 * @return 0 on success, < 0 on error with errno set:
919 * - EBADF dh is an invalid directory handle
921 * @see smbc_opendir()
926 int smbc_closedir(int dh
);
931 /**@ingroup directory
932 * Get multiple directory entries.
934 * smbc_getdents() reads as many dirent structures from the an open
935 * directory handle into a specified memory area as will fit.
937 * @param dh Valid directory as returned by smbc_opendir()
939 * @param dirp pointer to buffer that will receive the directory
942 * @param count The size of the dirp buffer in bytes
944 * @returns If any dirents returned, return will indicate the
945 * total size. If there were no more dirents available,
946 * 0 is returned. < 0 indicates an error.
947 * - EBADF Invalid directory handle
948 * - EINVAL Result buffer is too small or smbc_init
950 * - ENOENT No such directory.
951 * @see , smbc_dirent, smbc_readdir(), smbc_open()
953 * @todo Are errno values complete and correct?
955 * @todo Add example code so people know how to parse buffers.
960 int smbc_getdents(unsigned int dh
, struct smbc_dirent
*dirp
, int count
);
965 /**@ingroup directory
966 * Get a single directory entry.
968 * @param dh Valid directory as returned by smbc_opendir()
970 * @return A pointer to a smbc_dirent structure, or NULL if an
971 * error occurs or end-of-directory is reached:
972 * - EBADF Invalid directory handle
973 * - EINVAL smbc_init() failed or has not been called
975 * @see smbc_dirent, smbc_getdents(), smbc_open()
980 struct smbc_dirent
* smbc_readdir(unsigned int dh
);
985 /**@ingroup directory
986 * Get the current directory offset.
988 * smbc_telldir() may be used in conjunction with smbc_readdir() and
991 * @param dh Valid directory as returned by smbc_opendir()
993 * @return The current location in the directory stream or -1
994 * if an error occur. The current location is not
995 * an offset. Becuase of the implementation, it is a
996 * handle that allows the library to find the entry
998 * - EBADF dh is not a valid directory handle
999 * - EINVAL smbc_init() failed or has not been called
1000 * - ENOTDIR if dh is not a directory
1002 * @see smbc_readdir()
1008 off_t
smbc_telldir(int dh
);
1013 /**@ingroup directory
1014 * lseek on directories.
1016 * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
1017 * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
1019 * @param fd Valid directory as returned by smbc_opendir()
1021 * @param offset The offset (as returned by smbc_telldir). Can be
1022 * NULL, in which case we will rewind
1024 * @return 0 on success, -1 on failure
1025 * - EBADF dh is not a valid directory handle
1026 * - ENOTDIR if dh is not a directory
1027 * - EINVAL offset did not refer to a valid dirent or
1028 * smbc_init not called.
1030 * @see smbc_telldir()
1033 * @todo In what does the reture and errno values mean?
1038 int smbc_lseekdir(int fd
, off_t offset
);
1043 /**@ingroup directory
1044 * Create a directory.
1046 * @param durl The url of the directory to create
1048 * @param mode Specifies the permissions to use. It is modified
1049 * by the process's umask in the usual way: the
1050 * permissions of the created file are (mode & ~umask).
1052 * @return 0 on success, < 0 on error with errno set:
1053 * - EEXIST directory url already exists
1054 * - EACCES The parent directory does not allow write
1055 * permission to the process, or one of the directories
1056 * - ENOENT A directory component in pathname does not
1058 * - EINVAL NULL durl passed or smbc_init not called.
1059 * - ENOMEM Insufficient memory was available.
1067 int smbc_mkdir(const char *durl
, mode_t mode
);
1072 /**@ingroup directory
1073 * Remove a directory.
1075 * @param durl The smb url of the directory to remove
1077 * @return 0 on success, < 0 on error with errno set:
1078 * - EACCES or EPERM Write access to the directory
1079 * containing pathname was not allowed.
1080 * - EINVAL durl is NULL or smbc_init not called.
1081 * - ENOENT A directory component in pathname does not
1083 * - ENOTEMPTY directory contains entries.
1084 * - ENOMEM Insufficient kernel memory was available.
1086 * @see smbc_mkdir(), smbc_unlink()
1088 * @todo Are errno values complete and correct?
1093 int smbc_rmdir(const char *durl
);
1098 /**@ingroup attribute
1099 * Get information about a file or directory.
1101 * @param url The smb url to get information for
1103 * @param st pointer to a buffer that will be filled with
1104 * standard Unix struct stat information.
1106 * @return 0 on success, < 0 on error with errno set:
1107 * - ENOENT A component of the path file_name does not
1109 * - EINVAL a NULL url was passed or smbc_init not called.
1110 * - EACCES Permission denied.
1111 * - ENOMEM Out of memory
1112 * - ENOTDIR The target dir, url, is not a directory.
1120 int smbc_stat(const char *url
, struct stat
*st
);
1125 /**@ingroup attribute
1126 * Get file information via an file descriptor.
1128 * @param fd Open file handle from smbc_open() or smbc_creat()
1130 * @param st pointer to a buffer that will be filled with
1131 * standard Unix struct stat information.
1133 * @return EBADF filedes is bad.
1134 * - EACCES Permission denied.
1135 * - EBADF fd is not a valid file descriptor
1136 * - EINVAL Problems occurred in the underlying routines
1137 * or smbc_init not called.
1138 * - ENOMEM Out of memory
1140 * @see smbc_stat(), Unix stat()
1146 int smbc_fstat(int fd
, struct stat
*st
);
1151 /**@ingroup attribue
1152 * Change the ownership of a file or directory.
1154 * @param url The smb url of the file or directory to change
1157 * @param owner I have no idea?
1159 * @param group I have not idea?
1161 * @return 0 on success, < 0 on error with errno set:
1162 * - EPERM The effective UID does not match the owner
1163 * of the file, and is not zero; or the owner or group
1164 * were specified incorrectly.
1165 * - ENOENT The file does not exist.
1166 * - ENOMEM Insufficient was available.
1167 * - ENOENT file or directory does not exist
1169 * @todo Are we actually going to be able to implement this function
1171 * @todo How do we abstract owner and group uid and gid?
1177 int smbc_chown(const char *url
, uid_t owner
, gid_t group
);
1182 /**@ingroup attribute
1183 * Change the permissions of a file.
1185 * @param url The smb url of the file or directory to change
1188 * @param mode The permissions to set:
1189 * - Put good explaination of permissions here!
1191 * @return 0 on success, < 0 on error with errno set:
1192 * - EPERM The effective UID does not match the owner
1193 * of the file, and is not zero
1194 * - ENOENT The file does not exist.
1195 * - ENOMEM Insufficient was available.
1196 * - ENOENT file or directory does not exist
1198 * @todo Actually implement this fuction?
1200 * @todo Are errno values complete and correct?
1205 int smbc_chmod(const char *url
, mode_t mode
);
1210 /**@ingroup attribute
1211 * Change the last modification time on a file
1213 * @param url The smb url of the file or directory to change
1214 * the modification time of
1216 * @param tbuf A timeval structure which contains the desired
1217 * modification time. NOTE: Only the tv_sec field is
1218 * used. The tv_usec (microseconds) portion is ignored.
1220 * @return 0 on success, < 0 on error with errno set:
1221 * - EINVAL The client library is not properly initialized
1222 * - EPERM Permission was denied.
1228 int smbc_utimes(const char *url
, struct timeval
*tbuf
);
1234 /**@ingroup attribute
1235 * Change the last modification time on a file
1237 * @param url The smb url of the file or directory to change
1238 * the modification time of
1240 * @param utbuf A utimebuf structure which contains the desired
1241 * modification time. NOTE: Although the structure contains
1242 * an access time as well, the access time value is ignored.
1244 * @return 0 on success, < 0 on error with errno set:
1245 * - EINVAL The client library is not properly initialized
1246 * - ENOMEM No memory was available for internal needs
1247 * - EPERM Permission was denied.
1253 int smbc_utime(const char *fname
, struct utimbuf
*utbuf
);
1259 /**@ingroup attribute
1260 * Set extended attributes for a file. This is used for modifying a file's
1261 * security descriptor (i.e. owner, group, and access control list)
1263 * @param url The smb url of the file or directory to set extended
1266 * @param name The name of an attribute to be changed. Names are of
1267 * one of the following forms:
1269 * system.nt_sec_desc.<attribute name>
1270 * system.nt_sec_desc.*
1271 * system.nt_sec_desc.*+
1273 * where <attribute name> is one of:
1281 * acl+:<name or sid>
1283 * In the forms "system.nt_sec_desc.*" and
1284 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1285 * literal, i.e. the string is provided exactly as shown, and
1286 * the value parameter should contain a complete security
1287 * descriptor with name:value pairs separated by tabs,
1288 * commas, or newlines (not spaces!).
1290 * The plus sign ('+') indicates that SIDs should be mapped
1291 * to names. Without the plus sign, SIDs are not mapped;
1292 * rather they are simply converted to a string format.
1294 * @param value The value to be assigned to the specified attribute name.
1295 * This buffer should contain only the attribute value if the
1296 * name was of the "system.nt_sec_desc.<attribute_name>"
1297 * form. If the name was of the "system.nt_sec_desc.*" form
1298 * then a complete security descriptor, with name:value pairs
1299 * separated by tabs, commas, or newlines (not spaces!),
1300 * should be provided in this value buffer. A complete
1301 * security descriptor will contain one or more entries
1302 * selected from the following:
1304 * REVISION:<revision number>
1305 * OWNER:<sid or name>
1306 * GROUP:<sid or name>
1307 * ACL:<sid or name>:<type>/<flags>/<mask>
1309 * The revision of the ACL specifies the internal Windows NT
1310 * ACL revision for the security descriptor. If not specified
1311 * it defaults to 1. Using values other than 1 may cause
1312 * strange behaviour.
1314 * The owner and group specify the owner and group sids for
1315 * the object. If the attribute name (either '*+' with a
1316 * complete security descriptor, or individual 'owner+' or
1317 * 'group+' attribute names) ended with a plus sign, the
1318 * specified name is resolved to a SID value, using the
1319 * server on which the file or directory resides. Otherwise,
1320 * the value should be provided in SID-printable format as
1321 * S-1-x-y-z, and is used directly. The <sid or name>
1322 * associated with the ACL: attribute should be provided
1325 * @param size The number of the bytes of data in the value buffer
1327 * @param flags A bit-wise OR of zero or more of the following:
1328 * SMBC_XATTR_FLAG_CREATE -
1329 * fail if the named attribute already exists
1330 * SMBC_XATTR_FLAG_REPLACE -
1331 * fail if the attribute does not already exist
1333 * If neither flag is specified, the specified attributes
1334 * will be added or replace existing attributes of the same
1335 * name, as necessary.
1337 * @return 0 on success, < 0 on error with errno set:
1338 * - EINVAL The client library is not properly initialized
1339 * or one of the parameters is not of a correct
1341 * - ENOMEM No memory was available for internal needs
1342 * - EEXIST If the attribute already exists and the flag
1343 * SMBC_XATTR_FLAG_CREAT was specified
1344 * - ENOATTR If the attribute does not exist and the flag
1345 * SMBC_XATTR_FLAG_REPLACE was specified
1346 * - EPERM Permission was denied.
1347 * - ENOTSUP The referenced file system does not support
1348 * extended attributes
1350 * @note Attribute names are compared in a case-insensitive
1351 * fashion. All of the following are equivalent, although
1352 * the all-lower-case name is the preferred format:
1353 * system.nt_sec_desc.owner
1354 * SYSTEM.NT_SEC_DESC.OWNER
1355 * sYsTeM.nt_sEc_desc.owNER
1361 int smbc_setxattr(const char *url
,
1370 /**@ingroup attribute
1371 * Set extended attributes for a file. This is used for modifying a file's
1372 * security descriptor (i.e. owner, group, and access control list). The
1373 * POSIX function which this maps to would act on a symbolic link rather than
1374 * acting on what the symbolic link points to, but with no symbolic links in
1375 * SMB file systems, this function is functionally identical to
1378 * @param url The smb url of the file or directory to set extended
1381 * @param name The name of an attribute to be changed. Names are of
1382 * one of the following forms:
1384 * system.nt_sec_desc.<attribute name>
1385 * system.nt_sec_desc.*
1386 * system.nt_sec_desc.*+
1388 * where <attribute name> is one of:
1396 * acl+:<name or sid>
1398 * In the forms "system.nt_sec_desc.*" and
1399 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1400 * literal, i.e. the string is provided exactly as shown, and
1401 * the value parameter should contain a complete security
1402 * descriptor with name:value pairs separated by tabs,
1403 * commas, or newlines (not spaces!).
1405 * The plus sign ('+') indicates that SIDs should be mapped
1406 * to names. Without the plus sign, SIDs are not mapped;
1407 * rather they are simply converted to a string format.
1409 * @param value The value to be assigned to the specified attribute name.
1410 * This buffer should contain only the attribute value if the
1411 * name was of the "system.nt_sec_desc.<attribute_name>"
1412 * form. If the name was of the "system.nt_sec_desc.*" form
1413 * then a complete security descriptor, with name:value pairs
1414 * separated by tabs, commas, or newlines (not spaces!),
1415 * should be provided in this value buffer. A complete
1416 * security descriptor will contain one or more entries
1417 * selected from the following:
1419 * REVISION:<revision number>
1420 * OWNER:<sid or name>
1421 * GROUP:<sid or name>
1422 * ACL:<sid or name>:<type>/<flags>/<mask>
1424 * The revision of the ACL specifies the internal Windows NT
1425 * ACL revision for the security descriptor. If not specified
1426 * it defaults to 1. Using values other than 1 may cause
1427 * strange behaviour.
1429 * The owner and group specify the owner and group sids for
1430 * the object. If the attribute name (either '*+' with a
1431 * complete security descriptor, or individual 'owner+' or
1432 * 'group+' attribute names) ended with a plus sign, the
1433 * specified name is resolved to a SID value, using the
1434 * server on which the file or directory resides. Otherwise,
1435 * the value should be provided in SID-printable format as
1436 * S-1-x-y-z, and is used directly. The <sid or name>
1437 * associated with the ACL: attribute should be provided
1440 * @param size The number of the bytes of data in the value buffer
1442 * @param flags A bit-wise OR of zero or more of the following:
1443 * SMBC_XATTR_FLAG_CREATE -
1444 * fail if the named attribute already exists
1445 * SMBC_XATTR_FLAG_REPLACE -
1446 * fail if the attribute does not already exist
1448 * If neither flag is specified, the specified attributes
1449 * will be added or replace existing attributes of the same
1450 * name, as necessary.
1452 * @return 0 on success, < 0 on error with errno set:
1453 * - EINVAL The client library is not properly initialized
1454 * or one of the parameters is not of a correct
1456 * - ENOMEM No memory was available for internal needs
1457 * - EEXIST If the attribute already exists and the flag
1458 * SMBC_XATTR_FLAG_CREAT was specified
1459 * - ENOATTR If the attribute does not exist and the flag
1460 * SMBC_XATTR_FLAG_REPLACE was specified
1461 * - EPERM Permission was denied.
1462 * - ENOTSUP The referenced file system does not support
1463 * extended attributes
1465 * @note Attribute names are compared in a case-insensitive
1466 * fashion. All of the following are equivalent, although
1467 * the all-lower-case name is the preferred format:
1468 * system.nt_sec_desc.owner
1469 * SYSTEM.NT_SEC_DESC.OWNER
1470 * sYsTeM.nt_sEc_desc.owNER
1476 int smbc_lsetxattr(const char *url
,
1485 /**@ingroup attribute
1486 * Set extended attributes for a file. This is used for modifying a file's
1487 * security descriptor (i.e. owner, group, and access control list)
1489 * @param fd A file descriptor associated with an open file (as
1490 * previously returned by smbc_open(), to get extended
1493 * @param name The name of an attribute to be changed. Names are of
1494 * one of the following forms:
1496 * system.nt_sec_desc.<attribute name>
1497 * system.nt_sec_desc.*
1498 * system.nt_sec_desc.*+
1500 * where <attribute name> is one of:
1508 * acl+:<name or sid>
1510 * In the forms "system.nt_sec_desc.*" and
1511 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1512 * literal, i.e. the string is provided exactly as shown, and
1513 * the value parameter should contain a complete security
1514 * descriptor with name:value pairs separated by tabs,
1515 * commas, or newlines (not spaces!).
1517 * The plus sign ('+') indicates that SIDs should be mapped
1518 * to names. Without the plus sign, SIDs are not mapped;
1519 * rather they are simply converted to a string format.
1521 * @param value The value to be assigned to the specified attribute name.
1522 * This buffer should contain only the attribute value if the
1523 * name was of the "system.nt_sec_desc.<attribute_name>"
1524 * form. If the name was of the "system.nt_sec_desc.*" form
1525 * then a complete security descriptor, with name:value pairs
1526 * separated by tabs, commas, or newlines (not spaces!),
1527 * should be provided in this value buffer. A complete
1528 * security descriptor will contain one or more entries
1529 * selected from the following:
1531 * REVISION:<revision number>
1532 * OWNER:<sid or name>
1533 * GROUP:<sid or name>
1534 * ACL:<sid or name>:<type>/<flags>/<mask>
1536 * The revision of the ACL specifies the internal Windows NT
1537 * ACL revision for the security descriptor. If not specified
1538 * it defaults to 1. Using values other than 1 may cause
1539 * strange behaviour.
1541 * The owner and group specify the owner and group sids for
1542 * the object. If the attribute name (either '*+' with a
1543 * complete security descriptor, or individual 'owner+' or
1544 * 'group+' attribute names) ended with a plus sign, the
1545 * specified name is resolved to a SID value, using the
1546 * server on which the file or directory resides. Otherwise,
1547 * the value should be provided in SID-printable format as
1548 * S-1-x-y-z, and is used directly. The <sid or name>
1549 * associated with the ACL: attribute should be provided
1552 * @param size The number of the bytes of data in the value buffer
1554 * @param flags A bit-wise OR of zero or more of the following:
1555 * SMBC_XATTR_FLAG_CREATE -
1556 * fail if the named attribute already exists
1557 * SMBC_XATTR_FLAG_REPLACE -
1558 * fail if the attribute does not already exist
1560 * If neither flag is specified, the specified attributes
1561 * will be added or replace existing attributes of the same
1562 * name, as necessary.
1564 * @return 0 on success, < 0 on error with errno set:
1565 * - EINVAL The client library is not properly initialized
1566 * or one of the parameters is not of a correct
1568 * - ENOMEM No memory was available for internal needs
1569 * - EEXIST If the attribute already exists and the flag
1570 * SMBC_XATTR_FLAG_CREAT was specified
1571 * - ENOATTR If the attribute does not exist and the flag
1572 * SMBC_XATTR_FLAG_REPLACE was specified
1573 * - EPERM Permission was denied.
1574 * - ENOTSUP The referenced file system does not support
1575 * extended attributes
1577 * @note Attribute names are compared in a case-insensitive
1578 * fashion. All of the following are equivalent, although
1579 * the all-lower-case name is the preferred format:
1580 * system.nt_sec_desc.owner
1581 * SYSTEM.NT_SEC_DESC.OWNER
1582 * sYsTeM.nt_sEc_desc.owNER
1588 int smbc_fsetxattr(int fd
,
1597 /**@ingroup attribute
1598 * Get extended attributes for a file.
1600 * @param url The smb url of the file or directory to get extended
1603 * @param name The name of an attribute to be retrieved. Names are of
1604 * one of the following forms:
1606 * system.nt_sec_desc.<attribute name>
1607 * system.nt_sec_desc.*
1608 * system.nt_sec_desc.*+
1610 * where <attribute name> is one of:
1618 * acl+:<name or sid>
1620 * In the forms "system.nt_sec_desc.*" and
1621 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1622 * literal, i.e. the string is provided exactly as shown, and
1623 * the value parameter will return a complete security
1624 * descriptor with name:value pairs separated by tabs,
1625 * commas, or newlines (not spaces!).
1627 * The plus sign ('+') indicates that SIDs should be mapped
1628 * to names. Without the plus sign, SIDs are not mapped;
1629 * rather they are simply converted to a string format.
1631 * @param value A pointer to a buffer in which the value of the specified
1632 * attribute will be placed (unless size is zero).
1634 * @param size The size of the buffer pointed to by value. This parameter
1635 * may also be zero, in which case the size of the buffer
1636 * required to hold the attribute value will be returned,
1637 * but nothing will be placed into the value buffer.
1639 * @return 0 on success, < 0 on error with errno set:
1640 * - EINVAL The client library is not properly initialized
1641 * or one of the parameters is not of a correct
1643 * - ENOMEM No memory was available for internal needs
1644 * - EEXIST If the attribute already exists and the flag
1645 * SMBC_XATTR_FLAG_CREAT was specified
1646 * - ENOATTR If the attribute does not exist and the flag
1647 * SMBC_XATTR_FLAG_REPLACE was specified
1648 * - EPERM Permission was denied.
1649 * - ENOTSUP The referenced file system does not support
1650 * extended attributes
1656 int smbc_getxattr(const char *url
,
1664 /**@ingroup attribute
1665 * Get extended attributes for a file. The POSIX function which this maps to
1666 * would act on a symbolic link rather than acting on what the symbolic link
1667 * points to, but with no symbolic links in SMB file systems, this function
1668 * is functionally identical to smbc_getxattr().
1670 * @param url The smb url of the file or directory to get extended
1673 * @param name The name of an attribute to be retrieved. Names are of
1674 * one of the following forms:
1676 * system.nt_sec_desc.<attribute name>
1677 * system.nt_sec_desc.*
1678 * system.nt_sec_desc.*+
1680 * where <attribute name> is one of:
1688 * acl+:<name or sid>
1690 * In the forms "system.nt_sec_desc.*" and
1691 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1692 * literal, i.e. the string is provided exactly as shown, and
1693 * the value parameter will return a complete security
1694 * descriptor with name:value pairs separated by tabs,
1695 * commas, or newlines (not spaces!).
1697 * The plus sign ('+') indicates that SIDs should be mapped
1698 * to names. Without the plus sign, SIDs are not mapped;
1699 * rather they are simply converted to a string format.
1701 * @param value A pointer to a buffer in which the value of the specified
1702 * attribute will be placed (unless size is zero).
1704 * @param size The size of the buffer pointed to by value. This parameter
1705 * may also be zero, in which case the size of the buffer
1706 * required to hold the attribute value will be returned,
1707 * but nothing will be placed into the value buffer.
1709 * @return 0 on success, < 0 on error with errno set:
1710 * - EINVAL The client library is not properly initialized
1711 * or one of the parameters is not of a correct
1713 * - ENOMEM No memory was available for internal needs
1714 * - EEXIST If the attribute already exists and the flag
1715 * SMBC_XATTR_FLAG_CREAT was specified
1716 * - ENOATTR If the attribute does not exist and the flag
1717 * SMBC_XATTR_FLAG_REPLACE was specified
1718 * - EPERM Permission was denied.
1719 * - ENOTSUP The referenced file system does not support
1720 * extended attributes
1726 int smbc_lgetxattr(const char *url
,
1734 /**@ingroup attribute
1735 * Get extended attributes for a file.
1737 * @param fd A file descriptor associated with an open file (as
1738 * previously returned by smbc_open(), to get extended
1741 * @param name The name of an attribute to be retrieved. Names are of
1742 * one of the following forms:
1744 * system.nt_sec_desc.<attribute name>
1745 * system.nt_sec_desc.*
1746 * system.nt_sec_desc.*+
1748 * where <attribute name> is one of:
1756 * acl+:<name or sid>
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!).
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.
1769 * @param value A pointer to a buffer in which the value of the specified
1770 * attribute will be placed (unless size is zero).
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.
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
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
1794 int smbc_fgetxattr(int fd
,
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 url The smb url of the file or directory to remove the extended
1809 * @param name The name of an attribute to be removed. Names are of
1810 * one of the following forms:
1812 * system.nt_sec_desc.<attribute name>
1813 * system.nt_sec_desc.*
1814 * system.nt_sec_desc.*+
1816 * where <attribute name> is one of:
1824 * acl+:<name or sid>
1826 * In the forms "system.nt_sec_desc.*" and
1827 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1828 * literal, i.e. the string is provided exactly as shown, and
1829 * the value parameter will return a complete security
1830 * descriptor with name:value pairs separated by tabs,
1831 * commas, or newlines (not spaces!).
1833 * The plus sign ('+') indicates that SIDs should be mapped
1834 * to names. Without the plus sign, SIDs are not mapped;
1835 * rather they are simply converted to a string format.
1837 * @return 0 on success, < 0 on error with errno set:
1838 * - EINVAL The client library is not properly initialized
1839 * - ENOMEM No memory was available for internal needs
1840 * - EPERM Permission was denied.
1841 * - ENOTSUP The referenced file system does not support
1842 * extended attributes
1848 int smbc_removexattr(const char *url
,
1854 /**@ingroup attribute
1855 * Remove extended attributes for a file. This is used for modifying a file's
1856 * security descriptor (i.e. owner, group, and access control list) The POSIX
1857 * function which this maps to would act on a symbolic link rather than acting
1858 * on what the symbolic link points to, but with no symbolic links in SMB file
1859 * systems, this function is functionally identical to smbc_removexattr().
1861 * @param url The smb url of the file or directory to remove the extended
1864 * @param name The name of an attribute to be removed. Names are of
1865 * one of the following forms:
1867 * system.nt_sec_desc.<attribute name>
1868 * system.nt_sec_desc.*
1869 * system.nt_sec_desc.*+
1871 * where <attribute name> is one of:
1879 * acl+:<name or sid>
1881 * In the forms "system.nt_sec_desc.*" and
1882 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1883 * literal, i.e. the string is provided exactly as shown, and
1884 * the value parameter will return a complete security
1885 * descriptor with name:value pairs separated by tabs,
1886 * commas, or newlines (not spaces!).
1888 * The plus sign ('+') indicates that SIDs should be mapped
1889 * to names. Without the plus sign, SIDs are not mapped;
1890 * rather they are simply converted to a string format.
1892 * @return 0 on success, < 0 on error with errno set:
1893 * - EINVAL The client library is not properly initialized
1894 * - ENOMEM No memory was available for internal needs
1895 * - EPERM Permission was denied.
1896 * - ENOTSUP The referenced file system does not support
1897 * extended attributes
1903 int smbc_lremovexattr(const char *url
,
1909 /**@ingroup attribute
1910 * Remove extended attributes for a file. This is used for modifying a file's
1911 * security descriptor (i.e. owner, group, and access control list)
1913 * @param fd A file descriptor associated with an open file (as
1914 * previously returned by smbc_open(), to get extended
1917 * @param name The name of an attribute to be removed. Names are of
1918 * one of the following forms:
1920 * system.nt_sec_desc.<attribute name>
1921 * system.nt_sec_desc.*
1922 * system.nt_sec_desc.*+
1924 * where <attribute name> is one of:
1932 * acl+:<name or sid>
1934 * In the forms "system.nt_sec_desc.*" and
1935 * "system.nt_sec_desc.*+", the asterisk and plus signs are
1936 * literal, i.e. the string is provided exactly as shown, and
1937 * the value parameter will return a complete security
1938 * descriptor with name:value pairs separated by tabs,
1939 * commas, or newlines (not spaces!).
1941 * The plus sign ('+') indicates that SIDs should be mapped
1942 * to names. Without the plus sign, SIDs are not mapped;
1943 * rather they are simply converted to a string format.
1945 * @return 0 on success, < 0 on error with errno set:
1946 * - EINVAL The client library is not properly initialized
1947 * - ENOMEM No memory was available for internal needs
1948 * - EPERM Permission was denied.
1949 * - ENOTSUP The referenced file system does not support
1950 * extended attributes
1956 int smbc_fremovexattr(int fd
,
1962 /**@ingroup attribute
1963 * List the supported extended attribute names associated with a file
1965 * @param url The smb url of the file or directory to list the extended
1968 * @param list A pointer to a buffer in which the list of attributes for
1969 * the specified file or directory will be placed (unless
1972 * @param size The size of the buffer pointed to by list. This parameter
1973 * may also be zero, in which case the size of the buffer
1974 * required to hold all of the attribute names will be
1975 * returned, but nothing will be placed into the list buffer.
1977 * @return 0 on success, < 0 on error with errno set:
1978 * - EINVAL The client library is not properly initialized
1979 * - ENOMEM No memory was available for internal needs
1980 * - EPERM Permission was denied.
1981 * - ENOTSUP The referenced file system does not support
1982 * extended attributes
1984 * @note This function always returns all attribute names supported
1985 * by NT file systems, regardless of wether the referenced
1986 * file system supports extended attributes (e.g. a Windows
1987 * 2000 machine supports extended attributes if NTFS is used,
1988 * but not if FAT is used, and Windows 98 doesn't support
1989 * extended attributes at all. Whether this is a feature or
1990 * a bug is yet to be decided.
1995 int smbc_listxattr(const char *url
,
2002 /**@ingroup attribute
2003 * List the supported extended attribute names associated with a file The
2004 * POSIX function which this maps to would act on a symbolic link rather than
2005 * acting on what the symbolic link points to, but with no symbolic links in
2006 * SMB file systems, this function is functionally identical to
2009 * @param url The smb url of the file or directory to list the extended
2012 * @param list A pointer to a buffer in which the list of attributes for
2013 * the specified file or directory will be placed (unless
2016 * @param size The size of the buffer pointed to by list. This parameter
2017 * may also be zero, in which case the size of the buffer
2018 * required to hold all of the attribute names will be
2019 * returned, but nothing will be placed into the list buffer.
2021 * @return 0 on success, < 0 on error with errno set:
2022 * - EINVAL The client library is not properly initialized
2023 * - ENOMEM No memory was available for internal needs
2024 * - EPERM Permission was denied.
2025 * - ENOTSUP The referenced file system does not support
2026 * extended attributes
2028 * @note This function always returns all attribute names supported
2029 * by NT file systems, regardless of wether the referenced
2030 * file system supports extended attributes (e.g. a Windows
2031 * 2000 machine supports extended attributes if NTFS is used,
2032 * but not if FAT is used, and Windows 98 doesn't support
2033 * extended attributes at all. Whether this is a feature or
2034 * a bug is yet to be decided.
2039 int smbc_llistxattr(const char *url
,
2046 /**@ingroup attribute
2047 * List the supported extended attribute names associated with a file
2049 * @param fd A file descriptor associated with an open file (as
2050 * previously returned by smbc_open(), to get extended
2053 * @param list A pointer to a buffer in which the list of attributes for
2054 * the specified file or directory will be placed (unless
2057 * @param size The size of the buffer pointed to by list. This parameter
2058 * may also be zero, in which case the size of the buffer
2059 * required to hold all of the attribute names will be
2060 * returned, but nothing will be placed into the list buffer.
2062 * @return 0 on success, < 0 on error with errno set:
2063 * - EINVAL The client library is not properly initialized
2064 * - ENOMEM No memory was available for internal needs
2065 * - EPERM Permission was denied.
2066 * - ENOTSUP The referenced file system does not support
2067 * extended attributes
2069 * @note This function always returns all attribute names supported
2070 * by NT file systems, regardless of wether the referenced
2071 * file system supports extended attributes (e.g. a Windows
2072 * 2000 machine supports extended attributes if NTFS is used,
2073 * but not if FAT is used, and Windows 98 doesn't support
2074 * extended attributes at all. Whether this is a feature or
2075 * a bug is yet to be decided.
2080 int smbc_flistxattr(int fd
,
2088 * Print a file given the name in fname. It would be a URL ...
2090 * @param fname The URL of a file on a remote SMB server that the
2091 * caller wants printed
2093 * @param printq The URL of the print share to print the file to.
2095 * @return 0 on success, < 0 on error with errno set:
2097 * - EINVAL fname or printq was NULL or smbc_init not
2099 * and errors returned by smbc_open
2105 int smbc_print_file(const char *fname
, const char *printq
);
2111 * Open a print file that can be written to by other calls. This simply
2112 * does an smbc_open call after checking if there is a file name on the
2113 * URI. If not, a temporary name is added ...
2115 * @param fname The URL of the print share to print to?
2117 * @returns A file handle for the print file if successful.
2118 * Returns -1 if an error ocurred and errno has the values
2119 * - EINVAL fname was NULL or smbc_init not called.
2120 * - all errors returned by smbc_open
2126 int smbc_open_print_job(const char *fname
);
2132 * List the print jobs on a print share, for the moment, pass a callback
2134 * @param purl The url of the print share to list the jobs of
2136 * @param fn Callback function the receives printjob info
2138 * @return 0 on success, < 0 on error with errno set:
2139 * - EINVAL fname was NULL or smbc_init not called
2145 int smbc_list_print_jobs(const char *purl
, smbc_list_print_job_fn fn
);
2151 * Delete a print job
2153 * @param purl Url of the print share
2155 * @param id The id of the job to delete
2157 * @return 0 on success, < 0 on error with errno set:
2158 * - EINVAL fname was NULL or smbc_init not called
2160 * @todo what errno values are possible here?
2165 int smbc_unlink_print_job(const char *purl
, int id
);
2170 /**@ingroup callback
2171 * Remove a server from the cached server list it's unused.
2173 * @param context pointer to smb context
2175 * @param srv pointer to server to remove
2177 * @return On success, 0 is returned. 1 is returned if the server could not
2178 * be removed. Also useable outside libsmbclient.
2183 int smbc_remove_unused_server(SMBCCTX
* context
, SMBCSRV
* srv
);
2188 #endif /* SMBCLIENT_H_INCLUDED */