Documentation added May 2016
xcall MIAMEX, MX_SYNC {,ch, sts, flags}
(Unix only) MX_SYNC (MIAMEX 134) invokes one of the operating system "sync" commands to force some or all of the file system cached updates to be flushed to disk. Normally this operation is managed by the operating system in background, but there are times when you may want to be sure that file updates have been written to permanent disk prior to proceeding with then next application step.
Parameters
ch (Num) [in]
If specified and non-zero, just updates for the file currently open via that channel are flushed. Internally the operation uses the standard Unix library call fsync() or syncfs() or msync(), depending on the platform and whether the file has been memory mapped. Otherwise, if ch = 0 or not specified, all cached data and metadata updates are flushed using the sync() call.
sts (Signed Num) [out]
If specified, a status value will be returned here...
Group |
Description |
|---|---|
0 |
success |
-2 |
ch not open |
-3 |
file type unknown or not applicable (e.g. input only) |
-4 |
operation not supported on this platform (e.g. Windows) |
>0 |
operating system errno value (see MX_ERRNOMSG) |
flags (Num) [in]
If specified and set to 1, and ch > 0, and the platform supports GNU libraries, then syncfs() is used instead of fsync(). (syncfs flushes all of the data and metadata in the disk partition containing the specified file, whereas fsync only flushes the data and metadata for the specified file.)
Notes
Warning: Aside from being a relatively costly operation (in terms of performance), it is impossible to be certain that the data is actually written to permanent storage by the time the call returns. This is because even though the operating system may execute a synchronous write operation, there's no way to be sure that the disk driver (RAID, SAN, network, whatever) actually writes the data to the permanent media before returning. (It might have its own cache buffering system.)
History
2016 January, A-Shell 6.3.1502: Time elapsed in the sync() or fsync() call is now logged in microseconds if the XDEBUG trace flag set. This was motivated by suspicions that the sync() call is taking longer under CentOS/RHEL 6 and 7 than under CentOS/RHEL 5. Such suspicions can now be easily quantified. Also, fsyncing now supported for ISAM-A files—e.g. xcall miamex, mx_sync, ch {,sts}.
