The SHMEM_GET_SEALS and SHMEM_SET_SEALS commands allow retrieving and modifying the active set of seals on a file. They're only supported on selected file-systems (currently shmfs) and are linux-only. Signed-off-by: David Herrmann <dh.herrmann@xxxxxxxxx> --- man2/fcntl.2 | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) diff --git a/man2/fcntl.2 b/man2/fcntl.2 index c010a49..53d55a5 100644 --- a/man2/fcntl.2 +++ b/man2/fcntl.2 @@ -57,6 +57,8 @@ .\" Document F_SETOWN_EX and F_GETOWN_EX .\" 2010-06-17, Michael Kerrisk .\" Document F_SETPIPE_SZ and F_GETPIPE_SZ. +.\" 2014-03-19, David Herrmann <dh.herrmann@xxxxxxxxx> +.\" Document SHMEM_SET_SEALS and SHMEM_GET_SEALS .\" .TH FCNTL 2 2014-02-20 "Linux" "Linux Programmer's Manual" .SH NAME @@ -1064,6 +1066,94 @@ of buffer space currently used to store data produces the error .BR F_GETPIPE_SZ " (\fIvoid\fP; since Linux 2.6.35)" Return (as the function result) the capacity of the pipe referred to by .IR fd . +.SS File Sealing +Sealing files limits the set of allowed operations on a given file. For each +seal that is set on a file, a specific set of operations will fail with +.B EPERM +on this file from now on. The file is said to be sealed. A file does not have +any seals set by default. Moreover, most filesystems do not support sealing +(only shmfs implements it right now). The following seals are available: +.RS +.TP +.BR SHMEM_SEAL_SHRINK +If this seal is set, the file in question cannot be reduced in size. This +affects +.BR open (2) +with the +.B O_TRUNC +flag and +.BR ftruncate (2). +They will fail with +.B EPERM +if you try to shrink the file in question. Increasing the file size is still +possible. +.TP +.BR SHMEM_SEAL_GROW +If this seal is set, the size of the file in question cannot be increased. This +affects +.BR write (2) +if you write across size boundaries, +.BR ftruncate (2) +and +.BR fallocate (2). +These calls will fail with +.B EPERM +if you use them to increase the file size or write beyond size boundaries. If +you keep the size or shrink it, those calls still work as expected. +.TP +.BR SHMEM_SEAL_WRITE +If this seal is set, you cannot modify data contents of the file. Note that +shrinking or growing the size of the file is still possible and allowed. Thus, +this seal is normally used in combination with one of the other seals. This seal +affects +.BR write (2) +and +.BR fallocate (2) +(only in combination with the +.B FALLOC_FL_PUNCH_HOLE +flag). Those calls will fail with +.B EPERM +if this seal is set. Furthermore, trying to create new memory-mappings via +.BR mmap (2) +in combination with +.B MAP_SHARED +will also fail with +.BR EPERM . +.RE +.TP +.BR SHMEM_SET_SEALS " (\fIint\fP; since Linux TBD)" +Change the set of seals of the file referred to by +.I fd +to +.IR arg . +You are required to own an exclusive reference to the file in question in order +to modify the seals. Otherwise, this call will fail with +.BR EPERM . +There is one exception: If no seals are set, this restriction does not apply and +you can set seals even if you don't own an exclusive reference. However, in any +case there may not exist any shared writable mapping or this call will always +fail with +.BR EPERM . +These semantics guarantee that once you verified a specific set of seals is set +on a given file, nobody besides you (in case you own an exclusive reference) can +modify the seals, anymore. + +You own an exclusive reference to a file if, and only if, the file-descriptor +passed to +.BR fcntl (2) +is the only reference to the underlying inode. There must not be any duplicates +of this file-descriptor, no other open files to the same underlying inode, no +hard-links or any active memory mappings. +.TP +.BR SHMEM_GET_SEALS " (\fIvoid\fP; since Linux TBD)" +Return (as the function result) the current set of seals of the file referred to +by +.IR fd . +If no seals are set, 0 is returned. If the file does not support sealing, -1 is +returned and +.I errno +is set to +.BR EINVAL . .SH RETURN VALUE For a successful call, the return value depends on the operation: .TP 0.9i -- 1.9.0 -- To unsubscribe from this list: send the line "unsubscribe linux-fsdevel" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
