pldd.1, bpf.2, chdir.2, clone.2, fanotify_init.2, fanotify_mark.2, intro.2, ipc.2...

[thirdparty/man-pages.git] / man3 / ftok.3

diff --git a/man3/ftok.3 b/man3/ftok.3
index 0accb621b5f93199c4fe9adc6bfab6098df1d774..eb43247f0478276651dac962be9ed07cce41a774 100644 (file)
--- a/man3/ftok.3
+++ b/man3/ftok.3
@@ -1,5 +1,6 @@
 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
 .\"
+.\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
 .\" manual provided the copyright notice and this permission notice are
 .\" preserved on all copies.
@@ -8,7 +9,7 @@
 .\" manual under the conditions for verbatim copying, provided that the
 .\" entire resulting derived work is distributed under the terms of a
 .\" permission notice identical to this one.
-.\" 
+.\"
 .\" Since the Linux kernel and libraries are constantly changing, this
 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
 .\" responsibility for errors or omissions, or for damages resulting from
@@ -16,85 +17,104 @@
 .\" have taken the same level of care in the production of this manual,
 .\" which is licensed free of charge, as they might when working
 .\" professionally.
-.\" 
+.\"
 .\" Formatted or processed versions of this manual, if unaccompanied by
 .\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
 .\"
-.\" Modified 2001-11-28, by Michael Kerrisk, <mtk-manpages@gmx.net>
+.\" 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 2001-11-28 "Linux 2.4" "Linux Programmer's Manual" 
+.TH FTOK 3 2019-08-02 "GNU" "Linux Programmer's Manual"
 .SH NAME
 ftok \- convert a pathname and a project identifier to a System V IPC key
 .SH SYNOPSIS
 .nf
-.B
-# include <sys/types.h>
-.B
-# include <sys/ipc.h>
+.B #include <sys/types.h>
+.B #include <sys/ipc.h>
 .fi
-.sp
+.PP
 .BI "key_t ftok(const char *" pathname ", int " proj_id );
 .SH DESCRIPTION
 The
-.B ftok
+.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 non-zero) to generate a
-.B key_t
+(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).
-.LP
+.PP
 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
+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
-.B key_t
-value is returned. On failure \-1 is returned, with
+.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 "CONFORMING TO"
-XPG4
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lb
+l l l.
+Interface      Attribute       Value
+T{
+.BR ftok ()
+T}     Thread safety   MT-Safe
+.TE
+.SH CONFORMING TO
+POSIX.1-2001, POSIX.1-2008.
 .SH NOTES
-Under libc4 and libc5 (and under SunOS 4.x) the prototype was
-.RS
+On some ancient systems, the prototype was:
+.PP
+.in +4n
+.EX
 .BI "key_t ftok(char *" pathname ", char " proj_id );
-.RE
-Today
+.EE
+.in
+.PP
+Today,
 .I proj_id
 is an
-.BR int ,
-but still only 8 bits are used. Typical usage has an ASCII character
+.IR int ,
+but still only 8 bits are used.
+Typical usage has an ASCII character
 .IR proj_id ,
-that is why the behaviour is said to be undefined when
+that is why the behavior is said to be undefined when
 .I proj_id
 is zero.
-.LP
-Of course no guarantee can be given that the resulting
-.B key_t
-is unique. Typically, a best effort attempt combines the given
+.PP
+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 i\-node number, and the
-lower 8 bits of the device number into a 32\-bit result.
+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 "SEE ALSO"
+.SH SEE ALSO
 .BR msgget (2),
 .BR semget (2),
 .BR shmget (2),
 .BR stat (2),
-.BR ipc (5)
+.BR sysvipc (7)