Name
file_lock
Auth
yes
Description
Locks or unlocks a file descriptor fd.
This method works, depending on the type paramater:
type | Description |
0 | release a lock |
1 | get a shared lock |
2 | get an exclusive lock |
whence | Description |
0 | offset is from the start of the file |
1 | offset is from current offset |
2 | offset is from the end of the file |
Locks are advisory locks, that is, they are not enforced on readers/writers that are not trying to take a lock.
You may hold just one lock on a file region. If shared lock is to be converted to an exclusive lock, the conversion is not atomic - the shared lock MIGHT be released first, before acquiring the exclusive lock. That happens only if the request for the exclusive lock can not be satisfied at the moment. This is done to prevent two processes from deadlocking by first holding a shared lock on a file and later trying to convert it to an exclusive lock. Processes still can deadlock by acquiring TWO locks simultaneously (each) on different files/regions in different order.
The API servers do not perform any kind of deadlock detection.
Required
Parameter | Description |
fd | int the file descriptor, which is locked or unlocked |
type | int what operation is performed to the file lock |
Optional
Parameter | Description |
offset | int lock only bytes, starting from this position (default for offset is 0) |
length | int lock length bytes only, starting from offset (default for length is 0) |
whence | int how to interpred the offset (default for whence is 0) |
get | int if set, then only test is performed if the file region can be locked |
noblock | int set, if you do not wish the lock to block |
Output
The call is always successful unless read/write error is encountered. Result will be 0 regardless if lock was granted or not.
One should check the return field locked to see if lock was granted. Unlocking always sets locked to true, the same goes for blocking requests, as they are always successful (sooner or later).
So with result of 0 checking the value of locked makes sense only for non-blocking locks and for get checks.
Example
{ result: 0, locked: true }
Errors
Code | Description |
1000 | Log in required. |
1007 | Invalid or closed file descriptor. |
1008 | Please provide lock 'type'. |
1012 | Invalid lock type. Please provide type (supported values: 0, 1, 2). |
2000 | Log in failed. |
4000 | Too many login tries from this IP address. |
5004 | Read error. Try reopening the file. |