APIs in Category: lock | API version 1.5

lock-break lock-status-iter-end lock-status-iter-next lock-status-iter-start

NetApp Manage ONTAP

lock-break | [top]

> Breaks all specified locks. At least one input argument needs to be specified.

> Input Name | Range | Type | Description
> file-name |  | string optional | File name prefixed by "/vol/volX" style path. Input syntax of file-name is the same for all protocols. NOTE: Currently, breaking all locks of a file is not encouraged, as NFSv4 does not yet implement breaking of locks. If attempted, will lead to an inconsistent NFSv4 lock state. Specifying a protocol will prevent this by limiting the breaking of locks to that particular protocol. Also, breaking locks for proto "nfsv4" is explicitly disallowed.
> host |  | string optional | Identity of a host. It is the NetBIOS name or IP address of a CIFS cient, FQDN of a PFS client, IP address or FQDN of NLM (Nfsv2/Nfsv3) client, and IP address of NFSv4 client. If specified, then locks are printed for that host only. If not specified, then locks across all hosts are printed. NOTE: Currently, only CIFS protocol filters lock output by host name.
> owner |  | string optional | Name of the lock owner, viz., a username prefixed by an optional domain (and a backslash) for CIFS protocol ([domain\]username), IP address of caching filer suffixed by a colon and a filesystem ID of origin filer (IP:fsid) for PFS, and process-ID for NLM(Nfsv2/Nfsv3). The concept of an owner for NFSv4 is yet to be defined. If specified, then locks are printed for that owner only. If owner is not specified, locks across all owners are printed. NOTE: Currently, only CIFS protocol filters lock output by owner name.
> protocol |  | string optional | Name of the protocol (case-insensitive): "cifs" (CIFS), "nlm" (Nfsv2/Nfsv3), "nfsv4" (NFSv4), and "pfs"(PFS). If not specified, then all protocols are scanned for locks. If in that case, a host and/or owner were specified, then expect input syntax errors in "error" output field for protocols that define syntax of host or owner differently. However, scanning of locks is not aborted due to these syntax errors and instead all protocols are still scanned to completion.
> Output Name | Range | Type | Description
> errors |  | break-error[] optional | If a specific protocol encounters an error, e.g., a syntax error, this element is included in the output to indicate it because the error might be for specific protocols but not for other protocols and hence should not fail the entire API. This structure includes the same information (status, reason, errno) that is normally included in the "results" attribute of the API itself.

> Errno | Description
> EINTERNALERROR |  |

lock-status-iter-end | [top]

> Terminate a list iteration and clean up any saved info.

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

> License
> cifs

lock-status-iter-next | [top]

> Returns items from a previous call to cifs-lock-status-iter-start. This API actually prints out the required locks.

> Input Name | Range | Type | Description
> maximum |  | integer | The maximum number of lock entries to retrieve.
> tag |  | string | Tag from a previous cifs-lock-status-iter-start.
> Output Name | Range | Type | Description
> lock-status |  | lock-status-info[] | An array, one entry per each lock.
> records |  | integer | This tells you how many locks are being returned from this particular call to lock-status-iter-next. When this value is 0, you have retrieved everything.

lock-status-iter-start | [top]

> Gives information about one or more locks, the results of which are retrieved by using lock-status-iter-next. One or more of the defined inputs can be specified in tandem to get locks for specific cases. If none of the inputs are specified, then all the locks in the system are printed. If no protocol is specified but one or more of the other inputs are specified, then locks across all protocols, viz., CIFS, PFS, NLM (Nfsv2/Nfsv3), and NFSv4, are printed. In this case, it is possible for protocols that define syntax of specified input differently to generate input syntax errors. However, these errors do not stop scanning of locks for other protocols.

> Input Name | Range | Type | Description
> file-name |  | string optional | File name prefixed by "/vol/volX" style path. If not specified, then locks across all files are printed. Input syntax of file-name is the same for all protocols.
> host |  | string optional | Identity of a host. It is the NetBIOS name or IP address of a CIFS client, FQDN of a PFS client, IP address or FQDN of NLM (Nfsv2/Nfsv3) client, and IP address of NFSv4 client. If specified, then locks are printed for that host only. If not specified, then locks across all hosts are printed. NOTE: Currently, only CIFS protocol filters lock output by host name.
> owner |  | string optional | Name of the lock owner, viz., a username prefixed by an optional domain (and a backslash) for CIFS protocol ([domain\]username), IP address suffixed by a colon and a filesystem ID of caching filer (IP:fsid) for PFS, and process-ID for NLM(Nfsv2/Nfsv3). The concept of an owner for NFSv4 is yet to be defined. If specified, then locks are printed for that owner only. If owner is not specified, locks across all owners are printed. NOTE: Currently, only CIFS protocol filters lock output by owner name.
> protocol |  | string optional | Name of the protocol (case-insensitive): "cifs" (CIFS), "nlm" (Nfsv2/Nfsv3), "nfsv4" (NFSv4), and "pfs"(PFS). If not specified, then all protocols are scanned for locks. If in that case, a host and/or owner were specified, then expect input syntax errors in "error" output field for protocols that define syntax of host or owner differently. However, scanning of locks is not aborted due to these syntax errors and instead all protocols are still scanned to completion.
> Output Name | Range | Type | Description
> records |  | integer | Number which tells you how many items have been saved for future retrieval with lock-status-iter-next.
> tag |  | string | Tag to be used in subsequent calls to lock-status-iter-next.

> Errno | Description
> EINVAL |  |
> EPIERROR |  |
> EINTERNALERROR |  |

> License
> cifs

Element definition: break-error | [top]

> Information about a single error encountered by specific protocol(s).

> Name | Range | Type | Description
> err |  | string | The error string.

Element definition: lock-status-info | [top]

> Information about a single lock.

> Name | Range | Type | Description
> cifs-lock |  | cifs-lock optional | Information about CIFS lock.
> nfsv4-lock |  | nfsv4-lock optional | Information about NFSv4 lock.
> nlm-lock |  | nlm-lock optional | Information about NLM(Nfsv2/Nfsv3) lock.
> pfs-lock |  | pfs-lock optional | Information about PFS locks

Element definition: cifs-lock | [top]

> Information about a single CIFS lock.

> Name | Range | Type | Description
> absolute-path |  | string optional | Name of the absolute ("/vol/volX" style) path corresponding to the CIFS path present in the ONTAPI output element, path. NOTE: In certain cases, the absolute path is unavailable (e.g., due to insufficient memory or if the lock is a Delete-on-close lock.)
> bytelock-length |  | integer optional | Number of bytes (from bytelock-offset) that are locked.
> bytelock-offset |  | integer optional | Starting offset in file that gets bytelocked.
> fileid |  | integer optional | A unique number (withing filesystem) identifying the file associated with the lock.
> fsid |  | integer optional | Filesystem ID.
> host-ip |  | ip-address | IP address, in dotted-decimal format, of the CIFS client.
> host-name |  | string optional | NetBios name of the CIFS client. This may be unavailable in certain situations. In such cases, the ONTAPI element 'host-ip' alone provides identity of the host.
> is-bytelock-exclusive |  | boolean optional | Is true for exclusive bytelock, else false.
> lock-error |  | string optional | Error messages issued, e.g., low system memory or if the input syntax is not applicable to this protocol (but maybe applicable to other protocols), or else if this protocol is specified by the "protocol" input but the syntax of host, owner, or file parameters is wrong. NOTE: New error messages may be added in the future.
> mode |  | string optional | File access mode that can be one of the following: DelOnClose: Delete-on-close lock DelOnCloseWait: Waiting Delete-on-close lock SuperLock: Super lock, eg, used by antivirus scanner Oplock-Excl: Exclusive Oplock Oplock-Lvl2: Level-II Oplock or a string of form "AccessMode-ShareMode" with: AccessMode: RdWr(Read-Write), Read(Read-only) Writ(Write), None(No access) ShareMode: denyA(deny all), denyR(deny Read access) denyW(deny Write access), denyN(deny none)
> oplock-level |  | string optional | Oplock level (for non-Delete-on-close lock), which is "Excl" (Exclusive), "lvl2" (Level-II), or "None" (No oplock).
> owner |  | string optional | Name of the lock owner: a username prefixed by an optional domain (and a backslash) for CIFS protocol ([domain\]username).
> path |  | string optional | Name of the path for a file or directory or NT stream. NOTE: In certain cases, the path is unavailable (e.g., due to insufficient memory)
> pid |  | integer optional | Process-ID of SMB client holding the lock.
> state |  | string | State of the lock, being one of: GRANTED: The lock is granted and is not being revoked. Locks in this state are on the share-grant or byte-grant lists, depending on the lock type. REVOKING: The lock has just begun revocation. Locks in this state are also on share-grant or byte-grant lists, depending on the lock type. REVOKED: The lock is undergoing revocation and the protocol has marked it to be released. This is a transient state whereby the protocol indicates the results of lock revocation to the generic lock manager code. Locks in this state are on the share-grant or byte-grants lists, but are removed immediately. GWAITING: The lock is waiting to be granted. Locks in this state are on the share-wait list or one of the wait lists associated with a granted byte lock. Locks enter this state when they can't be granted because of a conflict and the lock parameters indicate that the caller is prepared to wait. EWAITING: The lock is waiting either to be granted or denied. Locks in this state are on the share-wait list or one of the wait lists associated with a granted byte lock. Locks enter this state when they can't be granted because of a conflict with a soft lock and lock parameters indicate they the caller is not prepared to wait. Generally, in this situation, the protocol is prepared to wait for a limited time to allow the revocation to be resolved so that it can be determined whether the lock is to be granted or denied. ADJUSTED: The lock is undergoing revocation and the protocol has marked it to be replaced by a hard lock which is equal to it or weaker. This is a transient state whereby the protocol indicates the results of lock revocation to the generic lock manager code. Locks in this state are on the share-grant or byte-grant lists, but are transitioned back to the granted state once the changes in the lock have been dealt with. DENIED: The lock has been denied. This is a temporary state used to mark locks that have, after waiting, been denied. This is so that when the lock state is noticed by a WAFL operation, appropriate information about the state of the request, including the denial status, will be available. Locks in this state are not in any of the per-file lists. TIMEDOUT: The wait for the lock has timed out. This is a * temporary state used to mark locks that have, after waiting, had the wait timed out. This is so that when the lock state is noticed by a WAFL operation, appropriate information about the state of the request, including the fact that it could not be granted due to a timeout, will be available. Locks in this state are not in any of the per-file lists. SUBSUMED: Kept in reserve by protocol while protected by an encompassing soft lock. This is a transient state used for locks which are one of a set of locks that will take the place of a lock being revoked. Locks in this state are in an internal list and not in any of the per-file lists. They are converted to the GRANTED state and put in the share-grant list as part of completing the revocation operation . GONE: About to be returned. This is a temporary state for lock objects that are to be freed as soon as any potential references to them are gone. Locks in this state are not on any of the per-file lists . UNUSED: The lock was just allocated. This is a temporary state for lock objects that have been allocated but have not yet been dealt with (i.e. granted, denied, set up to wait). Locks in this state are not on any of the per-file lists. NOTE: Future releases may have new lock states.
> type |  | string optional | Type of lock, either "share-level" or "byte-range". NOTE: Future releases might have new values.

Element definition: nfsv4-lock | [top]

> Information about a single NFSv4 lock.

> Name | Range | Type | Description
> bytelock-length |  | integer optional | Number of bytes (from bytelock-offset) that are locked.
> bytelock-offset |  | integer optional | Starting offset in file that gets bytelocked.
> fileid |  | integer optional | A unique number (withing filesystem) identifying the file associated with the lock.
> fsid |  | integer optional | Filesystem ID.
> host-ip |  | ip-address optional | IP address, in dotted-decimal format, of the NFSv4 host.
> is-bytelock-exclusive |  | boolean optional | Is true for exclusive bytelock, else false.
> lock-error |  | string optional | Error messages issued, e.g., if the input syntax is not applicable to this protocol (but maybe applicable to other protocols), or else if this protocol is specified by the "protocol" input but the syntax of host, owner, or file is wrong.
> mode |  | string optional | File access mode that can be one of the following: Deleg-Read: Read delegation Deleg-Wrt: Write delegation or a string of form "AccessMode-ShareMode" with: AccessMode: RdWr(Read-Write), Read(Read-only) Writ(Write), None(No access) ShareMode: denyA(deny all), denyR(deny Read access) denyW(deny Write access), denyN(deny none)
> owner |  | string optional | Name of the owner.
> path |  | string optional | Name of the path for a file or directory.
> pid |  | integer optional | Process-ID of NFSv4 client.
> state |  | string | State of the lock. See cifs-lock for description of all state values. NOTE: Future releases may have new lock states.
> state-index-table |  | integer optional | This is an index into a state table that contains entire NFSv4 state information of the filer.
> type |  | string optional | Type of lock, either "share-level" or "byte-range". NOTE: Future releases might have new values.

Element definition: nlm-lock | [top]

> Information about a single NLM(Nfsv2/Nfsv3) lock.

> Name | Range | Type | Description
> bytelock-length |  | integer optional | Number of bytes (from bytelock-offset) that are locked.
> bytelock-offset |  | integer optional | Starting offset in file that gets bytelocked.
> fileid |  | integer optional | A unique number (withing filesystem) identifying the file associated with the lock.
> fsid |  | integer optional | Filesystem ID.
> host |  | string optional | IP address (in dotted decimal format) or a fully qualified domain name.
> is-bytelock-exclusive |  | boolean optional | Is true for exclusive bytelock, else false.
> last-hop-caching-filer |  | string optional | Name of the last-hop downstream caching filer used to obtain this lock. Note that this filer is not the actual lock owner.
> lock-error |  | string optional | Error messages issued, e.g., if the input syntax is not applicable to this protocol (but maybe applicable to other protocols), or else if this protocol is specified by the "protocol" input but the syntax of host, owner, or file parameters is wrong.
> mode |  | string optional | File access mode of form "AccessMode-denyN" with: Access mode: RdWr(Read-Write), Read(Read-only) Writ(Write), None(No access)
> owner |  | integer optional | Name of the owner.
> path |  | string optional | Name of the path for a file or directory.
> state |  | string | State of the lock. See cifs-lock for description of all state values. NOTE: Future releases may have new lock states.
> type |  | string optional | Type of lock, either "share-level" or "byte-range". NOTE: Future releases might have new values.

Element definition: pfs-lock | [top]

> Information about a single PFS lock.

> Name | Range | Type | Description
> fileid |  | integer optional | A unique number (withing filesystem) identifying the file, associated with the lock, on the origin filer.
> fsid |  | integer optional | Filesystem ID of the filesystem on the origin filier holding the PFS lock.
> host-ip |  | ip-address optional | IP address, in dotted-decimal format, of the PFS host.
> host-name |  | string optional | Fully qualified domain name of PFS host holding the lock.
> lock-error |  | string optional | Error messages issued, e.g., if the input syntax is not applicable to this protocol (but maybe applicable to other protocols), or else if this protocol is specified by the "protocol" input but the syntax of host, owner, or file parameters is wrong.
> mode |  | string optional | File access mode that can be one of the following: Deleg-PfsRead: Read delegation or a string of form "AccessMode-ShareMode" with: AccessMode: RdWr(Read-Write), Read(Read-only) Writ(Write), None(No access) ShareMode: denyA(deny all), denyR(deny Read access) denyW(deny Write access), denyN(deny none)
> owner |  | string optional | Name of the lock owner: IP address (of the caching filer holding the PFS lock), suffixed by a colon, and filesystem ID (of the caching filesystem holding the PFS lock). Syntax is: "IP:fsid".
> path |  | string optional | Name of the path for a file or directory.
> state |  | string | State of the lock. See cifs-lock for description of all state values. NOTE: Future releases may have new lock states.
> type |  | string optional | Type of lock, which can only be "share-level". NOTE: Future releases might have new values.

Element definition: ip-address | [top]

> One ip address, in dotted-decimal format (for example, "192.168.11.12").

> [none]