|
APIs in Category: file |
Vserver API version 1.15 |
file-create-directory |
The path and filename values used in these APIs are "NFS" filenames by default. If a file is created with a name that is illegal in CIFS, CIFS access to the file will need to use the file's 8.3 name. Similarly, if two filenames created by these APIs differ only by case (e.g. "a" and "A"), CIFS access will see the 8.3 name for the second one created. |
| file-create-directory | [top] |
Create a directory.
Input Name Range Type Description path string
Path of the directory to be created. The value is expected to begin with /vol/ . perm string
Permission of the directory to be created. It's similar to Unix style permission bits: 0755 gives read/write/execute permissions to owner and read/execute to group and other users. It consists of 4 octal digits derived by adding up bits 4, 2 and 1. Omitted digits are assumed to be zeros. First digit selects the set user ID(4), set group ID (2) and sticky (1) attributes. The second digit selects permission for the owner of the file: read (4), write (2) and execute (1); the third selects permissions for other users in the same group; the fourth for other users not in the group. Note: Prior to Data ONTAP 7.3.1 this value was treated as a base-10 number.
Errno Description EONTAPI_EINVAL EONTAPI_EPERM EONTAPI_EEXIST EONTAPI_ENOENT EONTAPI_ENOSPC EINTERNALERROR EVSERVERNOTFOUND EAPIVSERVERMISSING EVOLUMEQUIESCED EVOLUMEBUSY
Vfiler-enabled Yes
| file-delete-directory | [top] |
Delete a directory.
Input Name Range Type Description path string
Path of the directory to delete. The value is expected to begin with /vol/ . The directory must be empty in order for this API to succeed.
Errno Description EONTAPI_ENOENT EVSERVERNOTFOUND EAPIVSERVERMISSING EVOLUMEQUIESCED EVOLUMEBUSY EINTERNALERROR
Vfiler-enabled Yes
| file-delete-file | [top] |
Delete a file.
Input Name Range Type Description path string
Path of the file or symlink to delete. The value is expected to begin with /vol/ .
Errno Description EONTAPI_ENOENT EVOLUMEQUIESCED EVOLUMEBUSY EVSERVERNOTFOUND EAPIVSERVERMISSING EINTERNALERROR
Vfiler-enabled Yes
| file-get-file-info | [top] |
Obtains the file information or properties.
Input Name Range Type Description path string
Pathname of the directory to list. The value is expected to begin with /vol/ . Output Name Range Type Description file-info file-info
File information from the stat() function.
Errno Description EONTAPI_ENOENT EVOLUMEQUIESCED EVOLUMEBUSY EVSERVERNOTFOUND EAPIVSERVERMISSING EINTERNALERROR EVOL_NOT_MOUNTED
Vfiler-enabled Yes
| file-get-space-reservation-info | [top] |
Queries the space reservation settings for the named file.
Input Name Range Type Description path string
File to be queried. Output Name Range Type Description is-fill-enabled boolean
Whether or not the file is set with fill. is-overwrite-enabled boolean
Whether or not the file is set with overwrite.
Errno Description EOPNOTSUPPORTED EFILENOTFOUND EINTERNALERROR EVOLUMEBUSY EVOLUMEDOESNOTEXIST
Vfiler-enabled Yes
| file-hole-range-query-iter | [top] |
Return ranges of holes in a file
Input Name Range Type Description length integer
The number of bytes to scan. If this is zero scan until end of file. If the length is not an integral multiple of the block size it will be rounded up to the end of the block. Range : [0..2^63-1] max-records [1..1024] integer
optional
The maximum number of records to return in this call. Default: 64 offset integer
The starting offset of the file from where the scan for holes should begin. If the offset is not an integral multiple of the block size it will be rounded down to the start of the block. Range : [0..2^63-1] path string
The full path of the file for which hole information is to be queried. Format must be of the following: /vol/my_vol/my_file tag string
optional
Specify the tag from the last call. It is usually not specified for the first call. For subsequent calls, copy values from the 'next-tag' obtained from the previous call. Output Name Range Type Description attributes-list hole-range-info[]
optional
The list of attributes of file objects. next-tag string
optional
Tag for the next call. Not present when there are no more file objects to return. num-records [0..1024] integer
The number of records returned in this call.
Errno Description EINVALIDINPUTERROR EONTAPI_ENOMEM EONTAPI_ESTALE EONTAPI_ERANGE EONTAPI_ENOENT EONTAPI_EINVAL EONTAPI_EOFFLINE
| file-list-directory-iter | [top] |
list of files in a given directory.
Input Name Range Type Description desired-attributes file-info[]
optional
Specify which attributes to return. If not set return all of them. max-records [0..1000] integer
optional
Maximum number of directory entries to retrieve. path string
Pathname of the directory to list. The value is expected to begin with /vol/ . query file-info[]
optional
not used - here to satisfy smfgen tag string
optional
Should be empty for first call. For subsequent calls should be the value returned by next-tag below. Output Name Range Type Description attributes-list file-info[]
Array with information for each file in the named directory. next-tag string
optional
Tag to be used in the next call to continue iteration. Will not be returned if there are no more entries. num-records [0..1000] integer
This tells you how many records are being returned from this particular call to file-list-directory-iter-next. When this value is 0, you have retrieved everything.
Errno Description EONTAPI_ENOENT EVOLUMEQUIESCED EVOLUMEBUSY EVSERVERNOTFOUND EAPIVSERVERMISSING E_DIRECTORY_CHANGED EINTERNALERROR EVOL_NOT_MOUNTED
| file-punch-hole-iter | [top] |
Punch hole in the file. Hole punching involves reclaiming of zero blocks (blocks filled with zeroes) by unallocating them and then direct or indirect blocks can be made to point to 0, instead of these zero blocks.
Input Name Range Type Description attributes-list hole-range-info[]
This is the array containing the ranges that need to be hole punched. path string
Path of the file. Format must be of the following: /vol/my_vol/path-to-file tag string
optional
Do not set on first iteration. Use value of next-tag on subseguent iterations. Output Name Range Type Description next-tag string
optional
Returned if not all ranges have been punched
Errno Description EINTERNALERROR EONTAPI_EINVAL EONTAPI_ENOENT EONTAPI_EACCES EONTAPI_ESTALE EONTAPI_EPERM
| file-read-file | [top] |
Read data from a named file. API will fail if length exceeds 1 MB. This API should only be used on normal files. The results for other file types such as LUNs is undefined.
Input Name Range Type Description length [0..1048576] integer
Number of bytes to read from the file. offset [0..2^63-1] integer
Offset into file to start reading from. path string
Name of the file to read. For example: "/vol/<volume>/<file>". Output Name Range Type Description data string
Data read from the file. The format of the data is ASCII hex characters, two characters representing one byte from the file. (This format allows the representation of 0-valued bytes.) length [0..1048576] integer
Number of bytes actually read from the file. If this value is 0, then you have attempted to read at or past the end of the file.
Errno Description EONTAPI_EACCES EONTAPI_ENOENT EVSERVERNOTFOUND EAPIVSERVERMISSING EVOLUMEQUIESCED EVOLUMEBUSY EINTERNALERROR
Vfiler-enabled Yes
| file-rename-file | [top] |
Rename a file or directory. Note that this API cannot be used to rename to a different volume.
Input Name Range Type Description from-path string
Original path of the file. The value must begin with /vol/ . to-path string
Final path of the file. The value must begin with /vol/ . All path components except the final file name must already exist.
Errno Description EONTAPI_ENOENT EONTAPI_EINVAL EONTAPI_EEXIST EONTAPI_EXDEV EVOLUMEQUIESCED EVOLUMEBUSY EVSERVERNOTFOUND EAPIVSERVERMISSING
| file-set-space-reservation-info | [top] |
Sets the space reservation settings for the named file. is-overwrite-enabled and is-fill-enabled both must be the same value.
Input Name Range Type Description is-fill-enabled boolean
optional
Whether or not to set the file with fill. is-overwrite-enabled boolean
optional
Whether or not to set the file with overwrite. path string
File to be queried.
Errno Description EFILENOTFOUND EINTERNALERROR EINVALIDINPUTERROR ESETSPCRESERROR EONTAPI_ENOSPC EONTAPI_EROFS EVOLUMEBUSY EONTAPI_EISVDISK EVOLUMEDOESNOTEXIST
Vfiler-enabled Yes
| file-truncate-file | [top] |
Truncate a file. Any data past the truncation point will be lost, of course.
Input Name Range Type Description path string
Path of the file to truncate. The value is expected to begin with /vol/ . size string
optional
If provided, the file size is set to this value. The default value is 0.
Errno Description EONTAPI_ENOENT EVOLUMEQUIESCED EVOLUMEBUSY EVSERVERNOTFOUND EAPIVSERVERMISSING
Vfiler-enabled Yes
| file-usage-get | [top] |
Reports unique bytes held in a file.
Input Name Range Type Description length integer
optional
Length of the range in bytes. If it is not specified, the range that is reported is from start-offset to end-of-file. Range : [0..2^63-1]. path string
File name to generate report: E.g., /vol/vol1/file1 start-offset integer
optional
Start range of file in bytes. If this is not specified, it is assumed to be beginning of file (offset 0). Range : [0..2^63-1]. Output Name Range Type Description total-bytes integer
Number of bytes held by this file. Range : [0..2^63-1]. unique-bytes integer
Number of bytes 'uniquely' held by this file. Range : [0..2^63-1].
Errno Description EVSERVERNOTFOUND EINVALIDINPUTERROR EINTERNALERROR EONTAPI_ENOENT EONTAPI_EINVAL EONTAPI_EAGAIN
| file-usage-result-get | [top] |
Used to poll and retrieve results for a previous file-usage-start call. EINPROGRESS indicates that the background job has not finished yet.
Input Name Range Type Description cookie string
Cookie that was returned in an earlier file-usage-start call. Output Name Range Type Description total-bytes integer
Number of bytes held by this file. Range : [0..2^63-1]. unique-bytes integer
Number of bytes 'uniquely' held by this file. Range : [0..2^63-1].
Errno Description EVSERVERNOTFOUND EINVALIDINPUTERROR EINTERNALERROR EONTAPI_EINVAL EONTAPI_ESTALE EONTAPI_EINPROGRESS
| file-usage-start | [top] |
Starts a background job to compute unique bytes held in a file. The result can be obtained by passing the cookie to file-usage-result-get call.
Input Name Range Type Description length integer
optional
Length of the range in bytes. If it is not specified, the range that is reported is from start-offset to end-of-file. Range : [0..2^63-1]. path string
File name to generate report: E.g., /vol/vol1/file1 start-offset integer
optional
Start range of file in bytes. If this is not specified, it is assumed to be beginning of file (offset 0). Range : [0..2^63-1]. Output Name Range Type Description cookie string
Cookie to be used with subsequent file-usage-result-get call.
Errno Description EVSERVERNOTFOUND EINVALIDINPUTERROR EINTERNALERROR EONTAPI_ENOENT EONTAPI_EINVAL EONTAPI_EAGAIN
| file-write-file | [top] |
Write data into a named file. If the file does not previously exist, it will be created - the owner of the file will be root and it will not be readable or writable by non-root users. API will fail if data exceeds 1 MB. This API should only be used on normal files. The results for other file types such as LUNs is undefined.
Input Name Range Type Description data string
Data to be written. The format of the data is ASCII hex characters, two characters representing one byte. Whitespace characters, for convenience in formatting, can be present in the value and are ignored. offset [-1..2^63-1] integer
Offset into file at which to start writing. If the offset is -1, the data is appended to the file. overwrite boolean
optional
If false, and the file already exists, then the API will fail, with an errno of EEXIST. This allows the client to ensure that it was the exclusive creator of the file. The default value is true. path string
Pathname of the file to write. For example: "/vol/<volume>/<file>". Output Name Range Type Description length [0..1048576] integer
Number of bytes actually written.
Errno Description EONTAPI_EACCES EONTAPI_ENOENT EBADFILELENGTH EVOLUMEQUIESCED EVOLUMEBUSY EVSERVERNOTFOUND EAPIVSERVERMISSING EINTERNALERROR
Vfiler-enabled Yes
| Element definition: file-info | [top] |
Information about a single file.
Name Range Type Description accessed-timestamp [0..2^32-1] integer
Last asscess time of the file. The value is in seconds since January 1, 1970. acl-type string
The type of access control list (acl) on the file. Possible values are: "no_acl", "nt_acl", "nfs_acl", and goddess forbid, "unknown". bytes-used [0..2^63-1] integer
optional
returns the number of bytes actually used on disk by this file changed-timestamp [0..2^32-1] integer
Last changed time of the file. The value is in seconds since January 1, 1970. creation-timestamp [0..2^32-1] integer
Creation time of the file. The value is in seconds since January 1, 1970. dsid [0..2^64-1] integer
optional
Data Set ID file-size [0..2^63-1] integer
The size of the file in bytes. file-type string
Type of the file. Possible values: file, directory, blockdev, chardev, symlink, socket, fifo, stream, lun. A cluster-mode volume can also return "junction". group-id [0..2^32-1] integer
The integer id of the group owner of the file. hard-links-count [0..2^32-1] integer
The number of hard links to the file. inode-gen-number [0..2^32-1] integer
optional
Inode generation number inode-number [0..2^32-1] integer
The file node number. is-empty boolean
optional
This element tells whether directory is empty or not. Directory is considered empty if it only contains entries for "." and "..". This element is present if file is directory. In some special error cases like volume goes offline in between or directory is moved in the middle of getting this info, this field might not get set. modified-timestamp [0..2^32-1] integer
Last modification time of the file. The value is in seconds since January 1, 1970. msid [0..2^64-1] integer
optional
Mirror Set ID name string
Name of the file. owner-id [0..2^32-1] integer
The integer id of the owner of the file. perm string
File permission bits. It's similar to Unix style permission bits: 0755 gives read/write/execute permissions to owner and read/execute to group and other users. It consists of 4 octal digits derived by adding up bits 4, 2 and 1. Omitted digits are assumed to be zeros. First digit selects the set user ID(4), set group ID (2) and sticky (1) attributes. The second digit selects permission for the owner of the file: read (4), write (2) and execute (1); the third selects permissions for other users in the same group; the fourth for other users not in the group.
| Element definition: hole-range-info | [top] |
The hole start need not be an integral multiple of the block size. It will be rounded up to the start of the next block. The hole-size does not need to be the size of a block. It will be rounded down to the beginning of the block. It is possible that after the adjustments there is nothing to punch. That is ok and will be treated as success. Note that presently in WAFL small files are entirely within the inode. It is possible to "hole punch" those however nothing happens. The data is left alone. Considering the use case fot this ZAPI and the amount of effort to code the "correct" solution this is deemed an acceptable condition.
Name Range Type Description hole-size integer
Size of the hole in terms of bytes. If punching a hole WAFL presently limits this value to 4MB. Range : [0..2^63-1] hole-start integer
Starting offset of the hole. Range : [0..2^63-1]