APIs in Category: file | API version 1.12

file-create-directory file-create-symlink file-delete-directory file-delete-file file-get-file-info file-get-fingerprint file-inode-info file-list-directory-iter-end file-list-directory-iter-next file-list-directory-iter-start file-read-file file-read-symlink file-rename-directory file-truncate-file 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).

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 |  | integer | 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.

> Errno | Description
> EONTAPI_EINVAL |  |
> EONTAPI_EPERM |  |
> EONTAPI_EEXIST |  |
> EONTAPI_ENOENT |  |
> EONTAPI_ENOSPC |  |
> EINTERNALERROR |  |

> Vfiler-enabled
> Yes

file-create-symlink | [top]

> Create a symlink.

> Input Name | Range | Type | Description
> path |  | string | Path of the symlink file to create. The value is expected to begin with /vol/.
> symlink |  | string | Value of the symlink.

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

> 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/.

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

> Vfiler-enabled
> Yes

file-get-fingerprint | [top]

> Get the fingerprint or digest of a file. Fingerprint is calculated using md5 or sha-256 digest algorithm depending on the algorithm specified. Fingerprint is calculated over the file data or metadata or on both data and metadata depending on the scope selected. Data fingerprint is calculated over file contents. Metadata fingerprint is calculated over the selected attributes of the file. Attributes used for metadata fingerprint calculations are file type (file-type), file size (file-size), file crtime (creation-time), file mtime (modified-time), file ctime (changed-time), file retention time (retention-time, is-wraparound), file uid (owner-id), file gid (group-id). File retention time is applicable to worm protected files only. The fingerprints are base64 encoded.

> Input Name | Range | Type | Description
> fingerprint-algorithm |  | digest-algorithm optional |
> fingerprint-scope |  | file-scope optional |
> path |  | string | Full path of the file to be fingerprinted. The value is expected to begin with /vol/.
> Output Name | Range | Type | Description
> fingerprint |  | fingerprint-info | Fingerprint, system, volume and file related information.

> Errno | Description
> EONTAPI_EINVAL |  |
> EONTAPI_ENOENT |  |
> EONTAPI_EIO |  |
> EONTAPI_EOFFLINE |  |
> EINTERNALERROR |  |

> Vfiler-enabled
> Yes

file-inode-info | [top]

> Get parent information for a given inode. This API corresponds to the "inodepath" diagnostic-level CLI in ONTAP-Classic, and has the same defaults. The input is: Required, a volume identifier. A volume may be specified by name, fsid, or (in some ONTAP products) UUID/DSID. Required, an inode number. Optional, a snapshot identifier to get information from a snapshot rather than the active volume. A snapshot may be specified by name or by id. Optional, various reporting flags (see below) to enable or disable optional output information.

The output is:

- All volume identifiers, the one used as input plus the values of the others.
- Optionally, all snapshot identifiers; the one used as input plus the value of the other.
- The number of parents for the inode.
- Optionally, one or more volume relative pathnames to the inode
- Optionally, one or more leaf names for the inode.
- Optionally, one or more of the actual parent info stored for the inode, in the form of the parent dir inode number and the parent directory cookie (fbn and offset into the fbn) used to find the dir entry that refers to the inode in the parent directory (ie. the info used to get the leaf name).

> Input Name | Range | Type | Description
> inode-number |  | integer | The inode number for which information is desired.
> report-leaf-name |  | boolean optional | If set to true, report the leaf name of the given inode. The leaf name is equivalent to the final component of a full pathname. For example, the leaf name of: /vol/vol0/foo/bar/baz is: baz By default, the inode's leaf name is not shown.
> report-no-pathname |  | boolean optional | If set to true, do not report on the given inode's full pathname. By default, the inode's full pathname is reported.
> report-other-parents |  | boolean optional | If set to true, report the requested information for all of the parents for the given inode. By default, only information about one of the given inode's parents is reported.
> report-parent-data |  | boolean optional | If set to true, report various other pieces of information about the given inode. This information includes the inode of the parent directory containing the given inode, along with the directory cookie by which the given inode is known in that parent directory inode. By default, this other information is not reported for the given inode.
> snap-id |  | integer optional | The snapshot number within the given volume in which the given inode is to be referenced. At most, one of snap-id or snap-name can be provided. If neither is provided, we reference the given inode within the active file system of the given volume. Valid snapshot ids have a range of 0 to (WAFL_SNAP_CNT - 1) (currently 255). A value of 0 will refer to the active file system of the given volume.
> snap-name |  | string optional | A snapshot name within the given volume in which the given inode is to be referenced. At most, one of snap-id or snap-name can be provided. If neither is provided, we reference the given inode within the active file system of the given volume.
> volume-dsid |  | string optional | The DSID (Data Set IDentifier) of the volume containing the given inode. Exactly one of volume-fsid, volume-name, volume-uuid or volume-dsid must be specified. DSIDs are formatted as 10-character strings composed of 8 hex characters prefixed with '0x'. NOTE: This form of volume identification is only supported in some ONTAP products (ONTAP-NG).
> volume-fsid |  | integer optional | The FSID (file system identifier) of the volume containing the given inode. Exactly one of volume-fsid, volume-name, volume-uuid, or volume-dsid must be specified. An FSID may have any uint32_t value.
> volume-name |  | string optional | The name of the volume containing the given inode. Exactly one of volume-fsid, volume-name, volume-uuid, or volume-dsid must be specified.
> volume-uuid |  | string optional | The UUID (Universally Unique IDentifier) of the volume containing the given inode. Exactly one of volume-fsid, volume-name, volume-uuid or volume-dsid must be specified. UUIDs are formatted as 36-character strings. These strings are composed of 32 hexadecimal characters broken up into five groupings separated by '-'s. The first grouping has 8 hex characters, the second through fourth groupings have four hex characters each, and the fifth and final grouping has 12 hex characters. Note that a leading '0x' is not used. An example UUID is 532ad684-c8ec-11d9-945f-00065b8c8a1e. NOTE: This form of volume identification is only supported in some ONTAP products (ONTAP-NG).
> Output Name | Range | Type | Description
> inode-number |  | integer | The number identifying the inode.
> inode-paths |  | inode-parent-info[] | List of requested paths and parent information for the given inode.
> number-of-parents |  | integer | The number of parents for the inode. For a file, this is the number of links to the file.
> snapshot-id |  | integer optional | The snapshot id, if requested info is from a snapshot.
> snapshot-name |  | string optional | The name of the snapshot, if requested info is from a snapshot.
> volume-dsid |  | string optional | The volume DSID.
> volume-fsid |  | integer | The volume FSID.
> volume-name |  | string | The volume name.
> volume-uuid |  | string | The volume UUID.

> Errno | Description
> EINVALIDINPUTERROR |  |
> EINODENUMBERTOOSMALL |  |
> EINODENUMBERTOOLARGE |  |
> EVOLUMEDOESNOTEXIST |  |
> ESNAPSHOTDOESNOTEXIST |  |
> EINVALIDINODE |  |
> EINELIGIBLEINODE |  |
> EPARENTINFONOTLOADED |  |
> EI2PNOTENABLED |  |
> EINTERNALERROR |  |
> EVOLUMEOFFLINE |  |

> Vfiler-enabled
> Yes

file-list-directory-iter-end | [top]

> Terminate a directory iteration.

> Input Name | Range | Type | Description
> tag |  | string | Tag from a previous file-list-directory-iter-start.

> Errno | Description
> EONTAPI_ENOENT |  |

> Vfiler-enabled
> Yes

file-list-directory-iter-next | [top]

> Obtain a list of files in a given directory.

> Input Name | Range | Type | Description
> maximum |  | integer | Maximum number of directory entries to retrieve.
> tag |  | string | Tag from a previous file-list-directory-iter-start.
> Output Name | Range | Type | Description
> files |  | file-info[] | Array with information for each file in the named directory.
> records |  | 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 |  |

> Vfiler-enabled
> Yes

file-list-directory-iter-start | [top]

> Start in iteration through the list of files in a given directory.

> 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
> records |  | integer | Number of items that have been saved for future retrieval with file-list-directory-iter-next.
> tag |  | string | Tag to be used in subsequent iterations.

> Errno | Description
> EONTAPI_ENOENT |  |

> Vfiler-enabled
> Yes

file-read-file | [top]

> Read data from a named file. API will fail if length exceeds 1 MB.

> Input Name | Range | Type | Description
> length |  | integer | Number of bytes to read from the file.
> offset |  | integer | Offset into file to start reading from.
> path |  | string | Name of the file to read, in the form "/vol//".
> 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 |  | 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_ENOENT |  |

> Vfiler-enabled
> Yes

file-read-symlink | [top]

> Read the contents of a symlink.

> Input Name | Range | Type | Description
> path |  | string | Path of the symlink file to read. The value is expected to begin with /vol/.
> Output Name | Range | Type | Description
> symlink |  | string | Value of the symlink. In other words, this is the destination path contained in the symlink.

> Vfiler-enabled
> Yes

file-rename-directory | [top]

> Rename a directory. Note that this API cannot be used to rename a directory to a different volume.

> Input Name | Range | Type | Description
> from-path |  | string | Original path of the directory. The value must begin with /vol/.
> to-path |  | string | Final path of the directory. The value must begin with /vol/. All path components except the final directory name must already exist.

> Errno | Description
> EONTAPI_ENOENT |  |
> EONTAPI_EINVAL |  |
> EONTAPI_ENOTDIR |  |
> EONTAPI_EEXIST |  |
> EONTAPI_EXDEV |  |

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

> Vfiler-enabled
> Yes

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.

> 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 |  | 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. The value is expected to begin with /vol/.
> Output Name | Range | Type | Description
> length |  | integer | Number of bytes actually written.

> Errno | Description
> EONTAPI_ENOENT |  |
> EBADFILELENGTH |  |

> Vfiler-enabled
> Yes

Element definition: digest-algorithm | [top]

> Digest algorithm used for fingerprint computation. Possible values: "sha-256" or "md5".

> [none]

Element definition: file-info | [top]

> Information about a single file.

> Name | Range | Type | Description
> accessed-timestamp |  | integer | Last asscess time of the file. The value is in seconds since January 1, 1970. Range : [0..2^31-1]
> 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".
> changed-timestamp |  | integer | Last changed time of the file. The value is in seconds since January 1, 1970. Range : [0..2^31-1]
> creation-timestamp |  | integer | Creation time of the file. The value is in seconds since January 1, 1970. Range : [0..2^31-1]
> file-size |  | integer | The size of the file in bytes. Range : [0..2^63-1]
> file-type |  | string | Type of the file. Possible values: file, directory, blockdev, chardev, symlink, socket, fifo, stream, lun.
> group-id |  | integer | The integer id of the group owner of the file. Range : [0..2^31-1]
> hard-links-count |  | integer | The number of hard links to the file. Range : [0..2^31-1]
> inode-number |  | integer | The file node number. Range : [0..2^31-1]
> 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, then this field goes missing.
> modified-timestamp |  | integer | Last modification time of the file. The value is in seconds since January 1, 1970. Range : [0..2^31-1]
> name |  | string | Name of the file.
> owner-id |  | integer | The integer id of the owner of the file. Range : [0..2^31-1]
> perm |  | integer | 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. Range : [0..2^31-1]

Element definition: file-scope | [top]

> Part of the file for which fingerprint is computed. Possible values: "metadata_only", "data_only", "data_and_metadata".

> [none]

Element definition: fingerprint-info | [top]

> Fingerprint information.

> Name | Range | Type | Description
> aggregate-uuid |  | string optional | Universal unique identifier (UUID) for the aggregate containing volume. The field is included for flexible volumes only.
> filer-id |  | string | ID (NVRAM ID) of owner.
> filer-name |  | string optional | Name of the filer. If the filer name has not been written to the disks, this will not be returned.
> fingerprint-algorithm |  | digest-algorithm |
> fingerprint-end-time |  | integer | End time of fingerprint computation in seconds since January 1, 1970. Time is taken out of system clock. Range : [0..2^64-1].
> fingerprint-input-path |  | string | Full path of the file to be fingerprinted. The value begins with /vol/.
> fingerprint-scope |  | file-scope |
> fingerprint-start-time |  | integer | Start time of fingerprint computation in seconds since January 1, 1970. Time is taken out of system clock. Range : [0..2^64-1].
> fingerprint-version |  | string | Version of the fingerprint output format.
> formatted-fingerprint-end-time |  | string | End time of fingerprint computation in a human readable format :: in GMT timezone. Time is taken out of system clock.
> formatted-fingerprint-start-time |  | string | Start time of fingerprint computation in a human readable format :: in GMT timezone. Time is taken out of system clock.
> formatted-snaplock-compliance-clock |  | string | If Compliance Clock is initialized then human readable time :: in GMT timezone. A value of "not_initalized" indicates that Compliance Clock has not been initialized.
> formatted-volume-expiry-date |  | string optional | Expiry date of the SnapLock volume in a human-readable format :: in GMT timezone. A value of "infinite" indicates that the volume has an infinite expiry date. A value of "scan_in_progress" indicates that expiry date is not displayed since worm scan on the volume is in progress. A value of "no_expiry_date" indicates that expiry date is not displayed since the SnapLock volume has no WORM files and WORM snapshots. This field is not included if the volume is offline or the volume is Non-Snaplock volume.
> is-volume-expiry-date-wraparound |  | boolean optional | True if the date represented in the field volume-expiry-date is a wraparound format. The wraparound format indicates that dates after 01/19/2038 are mapped from 01/01/1970 - 12/31/2002 to 01/19/2038 - 01/19/2071. The field is not included if volume-expiry-date is not included.
> metadata-files |  | file-fingerprint-info[] | List of files and their fingerprint related information.
> snaplock-compliance-clock |  | integer optional | If Compliance Clock is initialized then time in seconds in the standard UNIX format (since 01/01/1970 00:00:00) in GMT timezone. Range:[0..2^64-1].
> snaplock-license |  | string optional | Type of SnapLock license installed. Possible values: "compliance" that applies to SnapLock compliance restrictions and "enterprise" that applies to SnapLock enterprise restrictions and value "compliance and enterprise" if there are both licenses installed. This field is not included if SnapLock license is not installed.
> volume-containing-aggregate |  | string optional | Flexible volumes only. The name of the aggregate in which the given flexible volume resides.
> volume-expiry-date |  | integer optional | Expiry date of the SnapLock volume in seconds in the standard UNIX format (since 01/01/1970 00:00:00). Range:[0..2^64-1]. This field is not included if 1. Volume is Non-Snaplock volume, or 2. Snaplock volume has an infinite expiry date, or 3. Snaplock volume has no worm files or snapshots, or 4. Snaplock volume has worm scanner in progress The volume expiry date can be in wraparound format. The wraparound format indicates that dates after 01/19/2038 are mapped from 01/01/1970 - 12/31/2002 to 01/19/2038 - 01/19/2071.
> volume-name |  | string | Name of the volume.
> volume-snaplock-type |  | string optional | The type of the Snaplock volume. It is present for Snaplock volumes only. Possible values: "compliance" or "enterprise"
> volume-type |  | string | The type of volume. Possible values: "flexible" for flexible volumes, and "traditional" for traditional volumes.
> volume-uuid |  | string | Universal unique identifier (UUID) for the volume.

Element definition: inode-parent-info | [top]

> Inode's path and parent information.

> Name | Range | Type | Description
> inode-name |  | string optional | Name of inode in parent directory.
> inode-parent-cookie |  | integer optional | The opaque readdir cookie to determine the index of the inode in the parent directory tree. Note that this value is used as a testing hook, we do not plan to support its semantics and those semantics might change over time.
> inode-parent-inode-number |  | integer optional | Inode number of the parent directory.
> inode-path |  | string optional | Full path to inode

Element definition: digest-algorithm | [top]

> Digest algorithm used for fingerprint computation. Possible values: "sha-256" or "md5".

> [none]

Element definition: file-fingerprint-info | [top]

> Fingerprint information about single file.

> Name | Range | Type | Description
> access-time |  | integer optional | Last access time of the file attributes in seconds in the standard UNIX format since January 1, 1970 00:00:00. The field is included for regular files and files on Non-Snaplock volumes. Time is taken out of system clock. Range : [0..2^64-1]
> changed-time |  | integer | Last changed time of the file attributes in seconds in the standard UNIX format since January 1, 1970 00:00:00. For WORM files last change time for file attributes occurs when file is committed to WORM. Time is taken out of system clock for regular files and time is taken out of Compliance Clock when file is committed to worm. Range : [0..2^64-1]
> creation-time |  | integer | Creation time of the file in seconds in the standard UNIX format since January 1, 1970 00:00:00. Time is taken out of system clock. Range : [0..2^64-1]
> data-fingerprint |  | string optional | The digest value of data of the file. The fingerprint is base64 encoded. This field is not included if scope is 'metadata_only'.
> file-size |  | integer | The size of the file in bytes. Range : [0..2^64-1].
> file-type |  | string | Type of the file. Possible values: "worm", "worm_appendable", "worm_log" and "regular".
> fileid |  | integer | A unique number within filesystem identifying the file for fingerprint. Range : [0..2^31-1]
> formatted-access-time |  | string | Last access time of the file formatted in a human-readable format :: in GMT timezone. The field is included for regular files and files on Non-Snaplock volumes.
> formatted-changed-time |  | string | Last changed time of the file formatted in a human-readable format :: in GMT timezone.
> formatted-creation-time |  | string | Creation time of the file formatted in a human-readable format :: in GMT timezone.
> formatted-modified-time |  | string | Last modification time of the file formatted in a human-readable format :: in GMT timezone.
> formatted-retention-time |  | string optional | Expiry date of the worm file formatted in a human-readable format. This takes care of wraparound dates and prints the expiry date of the file in the format :: in GMT timezone. A value of "infinite" indicates that this file has infinite retention time. This field is not included for regular files and files on Non-Snaplock volumes.
> fsid |  | integer | Filesystem ID. Range : [0..2^31-1]
> group-id |  | integer | The integer id of the group owner of the file. Range : [0..2^31-1]
> is-wraparound |  | boolean optional | True if the date represented in retention-time is in wraparound format. The wraparound format indicates that dates after 01/19/2038 are mapped from 01/01/1970 - 12/31/2002 to 01/19/2038 - 01/19/2071. This field is not included if retention-time is not included.
> metadata-fingerprint |  | string optional | The digest value of metadata of the file The metadata fingerprint is calculated for file size, file ctime, file mtime, file crtime, file retention time, file uid, gid and file type. The fingerprint is base64 encoded. This field is not included if scope is 'data_only'.
> modified-time |  | integer | Last modification time of the file in seconds in the standard UNIX format since January 1, 1970 00:00:00. Time is taken out of system clock. Range : [0..2^64-1]
> owner-id |  | integer | The integer id of the owner of the file. Range : [0..2^31-1]
> owner-sid |  | string | The owner SID of the file. This field is included in the case when file has NTFS security style.
> path |  | string | Full path of the file that is fingerprinted. The value begins with /vol/.
> retention-time |  | integer optional | Retention time of the file in seconds in the standard UNIX format since January 1, 1970 00:00:00. This field is not included for regular files, files on Non-Snaplock volumes and files with infinite retention. The flag is-wraparound indicates that retention is in the wraparound format. The wraparound format indicates that dates after 01/19/2038 are mapped from 01/01/1970 - 12/31/2002 to 01/19/2038 - 01/19/2071 The time is taken out of Compliance Clock. Range : [0..2^64-1]

Element definition: file-scope | [top]

> Part of the file for which fingerprint is computed. Possible values: "metadata_only", "data_only", "data_and_metadata".

> [none]