APIs in Category: file | Vserver API version 1.21

file-create-directory file-delete-directory file-delete-file file-get-file-info file-get-space-reservation-info file-hole-range-query-iter file-list-directory-iter file-punch-hole-iter file-read-file file-rename-file file-set-space-reservation-info file-truncate-file file-usage-get file-usage-result-get file-usage-start file-write-file | 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. To access files or directories with Unicode file names, the UTF-8 equivalent of the Unicode path can be used. If a file contains Unicode-format data, the filer returns all the data in the file including the identifier in the first two bytes of the file which indicates the file contains Unicode data (0xFEFF). A file may optionally contain multiple distinct streams of data. A stream is an on disk structure containing a sequence of bytes, analogous to a file. A stream associated with a file is identified by a name, and data may be read or written to a file or stream. A stream can be thought of as a hidden file associated with a base file, and is visible in the name space of the base file. Streams are typically used to store metadata associated with the base file

NetApp Manage ONTAP

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 |  |
> EVSERVER_OP_NOT_ALLOWED |  |

> 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 |  |
> EVSERVER_OP_NOT_ALLOWED |  |

> 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 |  |
> EVSERVER_OP_NOT_ALLOWED |  |

> 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 |  |
> EVSERVER_OP_NOT_ALLOWED |  |

> 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..2^32-1] | 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..2^32-1] | integer | The number of records returned in this call.

> Errno | Description
> EINVALIDINPUTERROR |  |
> EONTAPI_ENOMEM |  |
> EONTAPI_ESTALE |  |
> EONTAPI_ERANGE |  |
> EONTAPI_ENOENT |  |
> EONTAPI_EINVAL |  |
> EONTAPI_EOFFLINE |  |
> EVSERVER_OP_NOT_ALLOWED |  |

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 | [1..2^32-1] | 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[] optional | 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..2^32-1] | 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 |  |
> EVSERVER_OP_NOT_ALLOWED |  |

file-punch-hole-iter | [top]

> Punch hole in the file. Hole punching involves reclaiming of blocks in a file by unallocating them and then direct or indirect blocks can be made to point to 0.

> 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 |  |
> EVSERVERNOTFOUND |  |
> EVOLUMEDOESNOTEXIST |  |
> EVOL_NOT_MOUNTED |  |
> EONTAPI_ENOSPC |  |

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 or streams associated with 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. If the value of offset is beyond the eof, the API will fail with EAPIERROR.
> path |  | string | Name of the file to read. For example: "/vol/<volume>/<file>".
> stream-name |  | string optional | A stream is an on disk structure which contains a sequence of bytes, analogous to a file. A stream is always associated with exactly one file. Characters that are valid for a file name are also valid for the stream-name. e.g., "meta", "resource1". Use this option if the data should be read from the named stream associated with file specified by <path> Default is empty stream name, in which case the data is read from file specified by <path> This field is available in Data ONTAP 8.2 or later.
> 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 |  |
> EAPIERROR |  |
> EVSERVER_OP_NOT_ALLOWED |  |

> 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 |  |
> EVSERVER_OP_NOT_ALLOWED |  |

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 |  |
> EVSERVER_OP_NOT_ALLOWED |  |

> 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 | [0..2^63-1] | integer optional | If provided, the file size in bytes is set to this value. The default value is 0.

> Errno | Description
> EONTAPI_ENOENT |  |
> EVOLUMEQUIESCED |  |
> EVOLUMEBUSY |  |
> EVSERVERNOTFOUND |  |
> EAPIVSERVERMISSING |  |
> EVSERVER_OP_NOT_ALLOWED |  |

> 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/stream 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 or streams associated with 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. The valid maximum value for (offset + data length) is the maximum total file size which is Data ONTAP version and file system dependent. If the value of the (offset + data length) is beyond the maximum total file size, the API will fail with EAPIERROR.
> 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>".
> stream-name |  | string optional | A stream is an on disk structure which contains a sequence of bytes, analogous to a file. A stream is always associated with exactly one file. Characters that are valid for a file name are also valid for the stream-name. e.g., "meta", "resource1". Use this option if the data should be written to the named stream associated with file specified by <path> Default is empty stream name, in which case the data is written to file specified by <path> This field is available in Data ONTAP 8.2 or later.
> 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 |  |
> EAPIERROR |  |
> EVSERVER_OP_NOT_ALLOWED |  |

> 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.
> 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.
> is-junction |  | boolean optional | Returns true if the directory is a junction.
> is-vm-aligned |  | boolean optional | Returns true if the file is vm-aligned. A vm-aligned file is a file which is padded with zero-filled data at the beginning so that it's actual data starts at a different offset instead of zero. This is done in VM environments so that reads/writes to this file are aligned to WAFL's 4k block boundary. The amount by which the start offset is adjusted depends on the vm-align setting of the hosting volume. Use the volume-list-info or the volume-get-iter API to get this information.
> 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 optional | 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. If the file is vm-aligned then the range chosen to hole-punch could be rounded down by a block to ensure that we don't punch block containing valid user data.

> 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]