Vely logo install

Vely 15.2.0 released on Jan 18, 2023
Articles updated Jan 17, 2023


Issues with this documentation page? Report here.


Locks file exclusively.


lock-file <file path> id [ define ] <lock id> status [ define ] <status>


lock-file attempts to create a file (deleting all contents of the previous file, if existed), and exclusively lock it. If successful, no other process can do the same unless current process ends or calls unlock-file. This statement is non-blocking, thus you can check in a sleepy loop for success.

<file path> should be either an existing or non-existing file with a valid file path.

<lock id> (in "id" clause) is a file descriptor associated with locked file.

<status> (in "status" clause) represents the status of file locking: VV_OKAY if successfully locked, VV_ERR_FAILED if cannot lock (likely because another process holds a lock), VV_ERR_INVALID if the path of the file is invalid (i.e. if it is empty), VV_ERR_CREATE if lock file cannot be created.

Generally, this statement is used for process control. A process would use lock-file to start working on a job that only one process can do at a time; once done, by using unlock-file statement, another process will be able to issue a successful lock-file call. Typically, lock-file is issued in a sleepy loop, waiting for a resource to be released.

Note that file lock is not carried across children processes (i.e. if your process creates children, such as with exec-program, then such children must obtain their own lock). In addition, if a process serving a request terminates before the request could issue unlock-file, the lock will be automatically released.

You can use any file name (likely choose a name that signifies the purpose of a lock, as long as you have permissions to create it), and create any number of them. This way you can create as many "binary semaphore"-like objects as you like.


// Get application home directory
get-app directory to define dir

// Create lock file name
write-string define fname
@<<p-out dir>>/.lock

// Enter loop in which something is done, OR, program waits for others to complete their work before doing its own
num lockid;
while (1) {

    // Attempt to lock file
    lock-file fname id lockid status define lockst

    // Check the status of locking
    if (lockst == VV_OKAY) {

        // File successfully locked, simulate working for 20 seconds
        sleep (20);
        // Exit while loop

    } else if (lockst == VV_ERR_FAILED) {

        // Another process holds the lock, wait, try again

    } else if (lockst == VV_ERR_OPEN || lockst == VV_ERR_INVALID) {

        // Errors
        @BAD LOCK

// Once done, unlock file
unlock-file id lockid

See also:

Files ( close-file   copy-file   delete-file   file-position   file_storage   file_uploading   lock-file   open-file   read-file   read-line   rename-file   stat-file   temporary_file   uniq-file   unlock-file   write-file  )  SEE ALL (documentation)

Copyright (c) 2022 DaSoftver LLC. Vely is a trademark of Dasoftver LLC. The software and information herein are provided "AS IS" and without any warranties or guarantees of any kind. Vely elephant logo (c) 2022 DaSoftver LLC. This web page is licensed under CC-BY-SA-4.0.