Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 110 insertions, 0 deletions

diff --git a/man/man3/ftok.3 b/man/man3/ftok.3
new file mode 100644
index 0000000..b8df38d
--- /dev/null
+++ b/man/man3/ftok.3
@@ -0,0 +1,110 @@
+'\" t
+.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified 2001-11-28, by Michael Kerrisk, <mtk.manpages@gmail.com>
+.\"	Changed data type of proj_id; minor fixes
+.\"	aeb: further fixes; added notes.
+.\"
+.TH ftok 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+ftok \- convert a pathname and a project identifier to a System V IPC key
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/ipc.h>
+.fi
+.P
+.BI "key_t ftok(const char *" pathname ", int " proj_id );
+.SH DESCRIPTION
+The
+.BR ftok ()
+function uses the identity of the file named by the given
+.I pathname
+(which must refer to an existing, accessible file)
+and the least significant 8 bits of
+.I proj_id
+(which must be nonzero) to generate a
+.I key_t
+type System V IPC key, suitable for use with
+.BR msgget (2),
+.BR semget (2),
+or
+.BR shmget (2).
+.P
+The resulting value is the same for all pathnames that
+name the same file, when the same value of
+.I proj_id
+is used.
+The value returned should be different when the
+(simultaneously existing) files or the project IDs differ.
+.SH RETURN VALUE
+On success, the generated
+.I key_t
+value is returned.
+On failure \-1 is returned, with
+.I errno
+indicating the error as for the
+.BR stat (2)
+system call.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR ftok ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.SH NOTES
+On some ancient systems, the prototype was:
+.P
+.in +4n
+.EX
+.BI "key_t ftok(char *" pathname ", char " proj_id );
+.EE
+.in
+.P
+Today,
+.I proj_id
+is an
+.IR int ,
+but still only 8 bits are used.
+Typical usage has an ASCII character
+.IR proj_id ,
+that is why the behavior is said to be undefined when
+.I proj_id
+is zero.
+.P
+Of course, no guarantee can be given that the resulting
+.I key_t
+is unique.
+Typically, a best-effort attempt combines the given
+.I proj_id
+byte, the lower 16 bits of the inode number, and the
+lower 8 bits of the device number into a 32-bit result.
+Collisions may easily happen, for example between files on
+.I /dev/hda1
+and files on
+.IR /dev/sda1 .
+.SH EXAMPLES
+See
+.BR semget (2).
+.SH SEE ALSO
+.BR msgget (2),
+.BR semget (2),
+.BR shmget (2),
+.BR stat (2),
+.BR sysvipc (7)