libsmbclient.h

samba-3.0.22.tar.gz 编译smb服务器的源码

 *                  selected from the following:
 *
 *                    REVISION:<revision number>
 *                    OWNER:<sid or name>
 *                    GROUP:<sid or name>
 *                    ACL:<sid or name>:<type>/<flags>/<mask>
 *
 *                  The  revision of the ACL specifies the internal Windows NT
 *                  ACL revision for the security descriptor. If not specified
 *                  it defaults to  1.  Using values other than 1 may cause
 *                  strange behaviour.
 *
 *                  The owner and group specify the owner and group sids for
 *                  the object. If the attribute name (either '*+' with a
 *                  complete security descriptor, or individual 'owner+' or
 *                  'group+' attribute names) ended with a plus sign, the
 *                  specified name is resolved to a SID value, using the
 *                  server on which the file or directory resides.  Otherwise,
 *                  the value should be provided in SID-printable format as
 *                  S-1-x-y-z, and is used directly.  The <sid or name>
 *                  associated with the ACL: attribute should be provided
 *                  similarly.
 *
 * @param size      The number of the bytes of data in the value buffer
 *
 * @param flags     A bit-wise OR of zero or more of the following:
 *                    SMBC_XATTR_FLAG_CREATE -
 *                      fail if the named attribute already exists
 *                    SMBC_XATTR_FLAG_REPLACE -
 *                      fail if the attribute does not already exist
 *
 *                  If neither flag is specified, the specified attributes
 *                  will be added or replace existing attributes of the same
 *                  name, as necessary.
 *
 * @return          0 on success, < 0 on error with errno set:
 *                  - EINVAL  The client library is not properly initialized
 *                            or one of the parameters is not of a correct
 *                            form
 *                  - ENOMEM No memory was available for internal needs
 *                  - EEXIST  If the attribute already exists and the flag
 *                            SMBC_XATTR_FLAG_CREAT was specified
 *                  - ENOATTR If the attribute does not exist and the flag
 *                            SMBC_XATTR_FLAG_REPLACE was specified
 *                  - EPERM   Permission was denied.
 *                  - ENOTSUP The referenced file system does not support
 *                            extended attributes
 *
 * @note            Attribute names are compared in a case-insensitive
 *                  fashion.  All of the following are equivalent, although
 *                  the all-lower-case name is the preferred format:
 *                    system.nt_sec_desc.owner
 *                    SYSTEM.NT_SEC_DESC.OWNER
 *                    sYsTeM.nt_sEc_desc.owNER
 *
 */
int smbc_lsetxattr(const char *url,
                   const char *name,
                   const void *value,
                   size_t size,
                   int flags);


/**@ingroup attribute
 * Set extended attributes for a file.  This is used for modifying a file's
 * security descriptor (i.e. owner, group, and access control list)
 *
 * @param fd        A file descriptor associated with an open file (as
 *                  previously returned by smbc_open(), to get extended
 *                  attributes for.
 * 
 * @param name      The name of an attribute to be changed.  Names are of
 *                  one of the following forms:
 *
 *                     system.nt_sec_desc.<attribute name>
 *                     system.nt_sec_desc.*
 *                     system.nt_sec_desc.*+
 *
 *                  where <attribute name> is one of:
 *
 *                     revision
 *                     owner
 *                     owner+
 *                     group
 *                     group+
 *                     acl:<name or sid>
 *                     acl+:<name or sid>
 *
 *                  In the forms "system.nt_sec_desc.*" and
 *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
 *                  literal, i.e. the string is provided exactly as shown, and
 *                  the value parameter should contain a complete security
 *                  descriptor with name:value pairs separated by tabs,
 *                  commas, or newlines (not spaces!).
 *
 *                  The plus sign ('+') indicates that SIDs should be mapped
 *                  to names.  Without the plus sign, SIDs are not mapped;
 *                  rather they are simply converted to a string format.
 *
 * @param value     The value to be assigned to the specified attribute name.
 *                  This buffer should contain only the attribute value if the
 *                  name was of the "system.nt_sec_desc.<attribute_name>"
 *                  form.  If the name was of the "system.nt_sec_desc.*" form
 *                  then a complete security descriptor, with name:value pairs
 *                  separated by tabs, commas, or newlines (not spaces!),
 *                  should be provided in this value buffer.  A complete
 *                  security descriptor will contain one or more entries
 *                  selected from the following:
 *
 *                    REVISION:<revision number>
 *                    OWNER:<sid or name>
 *                    GROUP:<sid or name>
 *                    ACL:<sid or name>:<type>/<flags>/<mask>
 *
 *                  The  revision of the ACL specifies the internal Windows NT
 *                  ACL revision for the security descriptor. If not specified
 *                  it defaults to  1.  Using values other than 1 may cause
 *                  strange behaviour.
 *
 *                  The owner and group specify the owner and group sids for
 *                  the object. If the attribute name (either '*+' with a
 *                  complete security descriptor, or individual 'owner+' or
 *                  'group+' attribute names) ended with a plus sign, the
 *                  specified name is resolved to a SID value, using the
 *                  server on which the file or directory resides.  Otherwise,
 *                  the value should be provided in SID-printable format as
 *                  S-1-x-y-z, and is used directly.  The <sid or name>
 *                  associated with the ACL: attribute should be provided
 *                  similarly.
 *
 * @param size      The number of the bytes of data in the value buffer
 *
 * @param flags     A bit-wise OR of zero or more of the following:
 *                    SMBC_XATTR_FLAG_CREATE -
 *                      fail if the named attribute already exists
 *                    SMBC_XATTR_FLAG_REPLACE -
 *                      fail if the attribute does not already exist
 *
 *                  If neither flag is specified, the specified attributes
 *                  will be added or replace existing attributes of the same
 *                  name, as necessary.
 *
 * @return          0 on success, < 0 on error with errno set:
 *                  - EINVAL  The client library is not properly initialized
 *                            or one of the parameters is not of a correct
 *                            form
 *                  - ENOMEM No memory was available for internal needs
 *                  - EEXIST  If the attribute already exists and the flag
 *                            SMBC_XATTR_FLAG_CREAT was specified
 *                  - ENOATTR If the attribute does not exist and the flag
 *                            SMBC_XATTR_FLAG_REPLACE was specified
 *                  - EPERM   Permission was denied.
 *                  - ENOTSUP The referenced file system does not support
 *                            extended attributes
 *
 * @note            Attribute names are compared in a case-insensitive
 *                  fashion.  All of the following are equivalent, although
 *                  the all-lower-case name is the preferred format:
 *                    system.nt_sec_desc.owner
 *                    SYSTEM.NT_SEC_DESC.OWNER
 *                    sYsTeM.nt_sEc_desc.owNER
 *
 */
int smbc_fsetxattr(int fd,
                   const char *name,
                   const void *value,
                   size_t size,
                   int flags);


/**@ingroup attribute
 * Get extended attributes for a file.
 *
 * @param url       The smb url of the file or directory to get extended
 *                  attributes for.
 * 
 * @param name      The name of an attribute to be retrieved.  Names are of
 *                  one of the following forms:
 *
 *                     system.nt_sec_desc.<attribute name>
 *                     system.nt_sec_desc.*
 *                     system.nt_sec_desc.*+
 *
 *                  where <attribute name> is one of:
 *
 *                     revision
 *                     owner
 *                     owner+
 *                     group
 *                     group+
 *                     acl:<name or sid>
 *                     acl+:<name or sid>
 *
 *                  In the forms "system.nt_sec_desc.*" and
 *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
 *                  literal, i.e. the string is provided exactly as shown, and
 *                  the value parameter will return a complete security
 *                  descriptor with name:value pairs separated by tabs,
 *                  commas, or newlines (not spaces!).
 *
 *                  The plus sign ('+') indicates that SIDs should be mapped
 *                  to names.  Without the plus sign, SIDs are not mapped;
 *                  rather they are simply converted to a string format.
 *
 * @param value     A pointer to a buffer in which the value of the specified
 *                  attribute will be placed (unless size is zero).
 *
 * @param size      The size of the buffer pointed to by value.  This parameter
 *                  may also be zero, in which case the size of the buffer
 *                  required to hold the attribute value will be returned,
 *                  but nothing will be placed into the value buffer.
 * 
 * @return          0 on success, < 0 on error with errno set:
 *                  - EINVAL  The client library is not properly initialized
 *                            or one of the parameters is not of a correct
 *                            form
 *                  - ENOMEM No memory was available for internal needs
 *                  - EEXIST  If the attribute already exists and the flag
 *                            SMBC_XATTR_FLAG_CREAT was specified
 *                  - ENOATTR If the attribute does not exist and the flag
 *                            SMBC_XATTR_FLAG_REPLACE was specified
 *                  - EPERM   Permission was denied.
 *                  - ENOTSUP The referenced file system does not support
 *                            extended attributes
 *
 */
int smbc_getxattr(const char *url,
                  const char *name,
                  const void *value,
                  size_t size);


/**@ingroup attribute
 * Get extended attributes for a file.  The POSIX function which this maps to
 * would act on a symbolic link rather than acting on what the symbolic link
 * points to, but with no symbolic links in SMB file systems, this function
 * is functionally identical to smbc_getxattr().
 *
 * @param url       The smb url of the file or directory to get extended
 *                  attributes for.
 * 
 * @param name      The name of an attribute to be retrieved.  Names are of
 *                  one of the following forms:
 *
 *                     system.nt_sec_desc.<attribute name>
 *                     system.nt_sec_desc.*
 *                     system.nt_sec_desc.*+
 *
 *                  where <attribute name> is one of:
 *
 *                     revision
 *                     owner
 *                     owner+
 *                     group
 *                     group+
 *                     acl:<name or sid>
 *                     acl+:<name or sid>
 *
 *                  In the forms "system.nt_sec_desc.*" and
 *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
 *                  literal, i.e. the string is provided exactly as shown, and
 *                  the value parameter will return a complete security
 *                  descriptor with name:value pairs separated by tabs,
 *                  commas, or newlines (not spaces!).
 *
 *                  The plus sign ('+') indicates that SIDs should be mapped
 *                  to names.  Without the plus sign, SIDs are not mapped;
 *                  rather they are simply converted to a string format.
 *
 * @param value     A pointer to a buffer in which the value of the specified
 *                  attribute will be placed (unless size is zero).
 *
 * @param size      The size of the buffer pointed to by value.  This parameter
 *                  may also be zero, in which case the size of the buffer
 *                  required to hold the attribute value will be returned,
 *                  but nothing will be placed into the value buffer.
 * 
 * @return          0 on success, < 0 on error with errno set:
 *                  - EINVAL  The client library is not properly initialized
 *                            or one of the parameters is not of a correct
 *                            form
 *                  - ENOMEM No memory was available for internal needs
 *                  - EEXIST  If the attribute already exists and the flag
 *                            SMBC_XATTR_FLAG_CREAT was specified
 *                  - ENOATTR If the attribute does not exist and the flag
 *                            SMBC_XATTR_FLAG_REPLACE was specified
 *                  - EPERM   Permission was denied.
 *                  - ENOTSUP The referenced file system does not support
 *                            extended attributes
 *
 */
int smbc_lgetxattr(const char *url,
                   const char *name,
                   const void *value,
                   size_t size);


/**@ingroup attribute
 * Get extended attributes for a file.
 *
 * @param fd        A file descriptor associated with an open file (as
 *                  previously returned by smbc_open(), to get extended
 *                  attributes for.
 * 
 * @param name      The name of an attribute to be retrieved.  Names are of
 *                  one of the following forms:
 *
 *                     system.nt_sec_desc.<attribute name>
 *                     system.nt_sec_desc.*
 *                     system.nt_sec_desc.*+
 *
 *                  where <attribute name> is one of:
 *
 *                     revision
 *                     owner
 *                     owner+
 *                     group
 *                     group+
 *                     acl:<name or sid>
 *                     acl+:<name or sid>
 *
 *                  In the forms "system.nt_sec_desc.*" and
 *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
 *                  literal, i.e. the string is provided exactly as shown, and
 *                  the value parameter will return a complete security
 *                  descriptor with name:value pairs separated by tabs,
 *                  commas, or newlines (not spaces!).
 *
 *                  The plus sign ('+') indicates that SIDs should be mapped
 *                  to names.  Without the plus sign, SIDs are not mapped;
 *                  rather they are simply converted to a string format.
 *
 * @param value     A pointer to a buffer in which the value of the specified
 *                  attrib