Use a single-font-change macro for a single argument. The output from "nroff" and "groff" is unchanged. Signed-off-by: Bjarni Ingi Gislason <bjarniig@xxxxxxxxx> --- man2/open.2 | 68 ++++++++++++++++++------------------- man2/open_by_handle_at.2 | 72 ++++++++++++++++++++-------------------- 2 files changed, 70 insertions(+), 70 deletions(-) diff --git a/man2/open.2 b/man2/open.2 index f38e1c1e0..ce1257f59 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -253,7 +253,7 @@ created by (This kind of race is in principle possible for any system call that creates a file descriptor whose close-on-exec flag should be set, and various other Linux system calls provide an equivalent of the -.BR O_CLOEXEC +.B O_CLOEXEC flag to deal with this problem.) .\" This flag fixes only one form of the race condition; .\" The race can also occur with, for example, file descriptors @@ -515,7 +515,7 @@ The effective UID of the process matches the owner UID of the file. .IP * The calling process has the -.BR CAP_FOWNER +.B CAP_FOWNER capability in its user namespace and the owner UID of the file has a mapping in the namespace. .RE @@ -550,7 +550,7 @@ This flag is a FreeBSD extension, which was added to Linux in version 2.1.126, and has subsequently been standardized in POSIX.1-2008. .IP See also -.BR O_PATH +.B O_PATH below. .\" The headers from glibc 2.0.100 and later include a .\" definition of this flag; \fIkernels before 2.1.126 will ignore it if @@ -646,32 +646,32 @@ etc.). .IP * Getting and setting file descriptor flags .RB ( fcntl (2) -.BR F_GETFD +.B F_GETFD and .BR F_SETFD ). .IP * Retrieving open file status flags using the .BR fcntl (2) -.BR F_GETFL +.B F_GETFL operation: the returned flags will include the bit .BR O_PATH . .IP * Passing the file descriptor as the -.IR dirfd +.I dirfd argument of .BR openat () and the other "*at()" system calls. This includes .BR linkat (2) with -.BR AT_EMPTY_PATH +.B AT_EMPTY_PATH (or via procfs using .BR AT_SYMLINK_FOLLOW ) even if the file is not a directory. .IP * Passing the file descriptor to another process via a UNIX domain socket (see -.BR SCM_RIGHTS +.B SCM_RIGHTS in .BR unix (7)). .RE @@ -708,7 +708,7 @@ does not require read permission on the object. If .I pathname is a symbolic link and the -.BR O_NOFOLLOW +.B O_NOFOLLOW flag is also specified, then the call returns a file descriptor referring to the symbolic link. This file descriptor can be used as the @@ -987,10 +987,10 @@ the call was interrupted by a signal handler; see .TP .B EINVAL The filesystem does not support the -.BR O_DIRECT +.B O_DIRECT flag. See -.BR NOTES +.B NOTES for more information. .TP .B EINVAL @@ -1049,14 +1049,14 @@ Too many symbolic links were encountered in resolving was a symbolic link, and .I flags specified -.BR O_NOFOLLOW +.B O_NOFOLLOW but not .BR O_PATH . .TP .B EMFILE The per-process limit on the number of open file descriptors has been reached (see the description of -.BR RLIMIT_NOFILE +.B RLIMIT_NOFILE in .BR getrlimit (2)). .TP @@ -1131,7 +1131,7 @@ The file is a device special file and no corresponding device exists. .B ENXIO The file is a UNIX domain socket. .TP -.BR EOPNOTSUPP +.B EOPNOTSUPP The filesystem containing .I pathname does not support @@ -1225,7 +1225,7 @@ The .BR O_NOATIME , .BR O_PATH , and -.BR O_TMPFILE +.B O_TMPFILE flags are Linux-specific. One must define .B _GNU_SOURCE @@ -1235,13 +1235,13 @@ The .BR O_CLOEXEC , .BR O_DIRECTORY , and -.BR O_NOFOLLOW +.B O_NOFOLLOW flags are not specified in POSIX.1-2001, but are specified in POSIX.1-2008. Since glibc 2.12, one can obtain their definitions by defining either .B _POSIX_C_SOURCE with a value greater than or equal to 200809L or -.BR _XOPEN_SOURCE +.B _XOPEN_SOURCE with a value greater than or equal to 700. In glibc 2.11 and earlier, one obtains the definitions by defining .BR _GNU_SOURCE . @@ -1365,31 +1365,31 @@ flags .BR O_SYNC , .BR O_DSYNC , and -.BR O_RSYNC +.B O_RSYNC for controlling the behavior. Regardless of whether an implementation supports this option, it must at least support the use of -.BR O_SYNC +.B O_SYNC for regular files. .PP Linux implements -.BR O_SYNC +.B O_SYNC and .BR O_DSYNC , but not .BR O_RSYNC . (Somewhat incorrectly, glibc defines -.BR O_RSYNC +.B O_RSYNC to have the same value as .BR O_SYNC .) .PP -.BR O_SYNC +.B O_SYNC provides synchronized I/O .I file integrity completion, meaning write operations will flush data and all associated metadata to the underlying hardware. -.BR O_DSYNC +.B O_DSYNC provides synchronized I/O .I data integrity completion, @@ -1412,39 +1412,39 @@ file will change the file length. The last modification timestamp is not needed to ensure that a read completes successfully, but the file length is. Thus, -.BR O_DSYNC +.B O_DSYNC would only guarantee to flush updates to the file length metadata (whereas -.BR O_SYNC +.B O_SYNC would also always flush the last modification timestamp metadata). .PP Before Linux 2.6.33, Linux implemented only the -.BR O_SYNC +.B O_SYNC flag for .BR open (). However, when that flag was specified, most filesystems actually provided the equivalent of synchronized I/O .I data integrity completion (i.e., -.BR O_SYNC +.B O_SYNC was actually implemented as the equivalent of .BR O_DSYNC ). .PP Since Linux 2.6.33, proper -.BR O_SYNC +.B O_SYNC support is provided. However, to ensure backward binary compatibility, -.BR O_DSYNC +.B O_DSYNC was defined with the same value as the historical .BR O_SYNC , and -.BR O_SYNC +.B O_SYNC was defined as a new (two-bit) flag value that includes the -.BR O_DSYNC +.B O_DSYNC flag value. This ensures that applications compiled against new headers get at least -.BR O_DSYNC +.B O_DSYNC semantics on pre-2.6.33 kernels. .\" .SS C library/kernel differences @@ -1637,7 +1637,7 @@ system call, if the memory buffer is a private mapping (i.e., any mapping created with the .BR mmap (2) -.BR MAP_PRIVATE +.B MAP_PRIVATE flag; this includes memory allocated on the heap and statically allocated buffers). Any such I/Os, whether submitted via an asynchronous I/O interface or from @@ -1747,7 +1747,7 @@ When both and .B O_DIRECTORY are specified in -.IR flags +.I flags and the file specified by .I pathname does not exist, diff --git a/man2/open_by_handle_at.2 b/man2/open_by_handle_at.2 index 877e7bea4..dd2aaf3c0 100644 --- a/man2/open_by_handle_at.2 +++ b/man2/open_by_handle_at.2 @@ -61,9 +61,9 @@ The .BR name_to_handle_at () system call returns a file handle and a mount ID corresponding to the file specified by the -.IR dirfd +.I dirfd and -.IR pathname +.I pathname arguments. The file handle is returned via the argument .IR handle , @@ -84,7 +84,7 @@ It is the caller's responsibility to allocate the structure with a size large enough to hold the handle returned in .IR f_handle . Before the call, the -.IR handle_bytes +.I handle_bytes field should be initialized to contain the allocated size for .IR f_handle . (The constant @@ -95,24 +95,24 @@ specifies the maximum expected size for a file handle. It is not a guaranteed upper limit as future filesystems may require more space.) Upon successful return, the -.IR handle_bytes +.I handle_bytes field is updated to contain the number of bytes actually written to .IR f_handle . .PP The caller can discover the required size for the .I file_handle structure by making a call in which -.IR handle->handle_bytes +.I handle->handle_bytes is zero; in this case, the call fails with the error -.BR EOVERFLOW +.B EOVERFLOW and -.IR handle->handle_bytes +.I handle->handle_bytes is set to indicate the required size; the caller can then use this information to allocate a structure of the correct size (see EXAMPLE below). Some care is needed here as -.BR EOVERFLOW +.B EOVERFLOW can also indicate that no file handle is available for this particular name in a filesystem which does normally support file-handle lookup. This case can be detected when the @@ -122,20 +122,20 @@ error is returned without being increased. .PP Other than the use of the -.IR handle_bytes +.I handle_bytes field, the caller should treat the -.IR file_handle +.I file_handle structure as an opaque data type: the -.IR handle_type +.I handle_type and -.IR f_handle +.I f_handle fields are needed only by a subsequent call to .BR open_by_handle_at (). .PP The .I flags argument is a bit mask constructed by ORing together zero or more of -.BR AT_EMPTY_PATH +.B AT_EMPTY_PATH and .BR AT_SYMLINK_FOLLOW , described below. @@ -152,13 +152,13 @@ If is a nonempty string containing an absolute pathname, then a handle is returned for the file referred to by that pathname. In this case, -.IR dirfd +.I dirfd is ignored. .IP * If .I pathname is a nonempty string containing a relative pathname and -.IR dirfd +.I dirfd has the special value .BR AT_FDCWD , then @@ -169,7 +169,7 @@ and a handle is returned for the file to which it refers. If .I pathname is a nonempty string containing a relative pathname and -.IR dirfd +.I dirfd is a file descriptor referring to a directory, then .I pathname is interpreted relative to the directory referred to by @@ -186,7 +186,7 @@ is an empty string and specifies the value .BR AT_EMPTY_PATH , then -.IR dirfd +.I dirfd can be an open file descriptor referring to any type of file, or .BR AT_FDCWD , @@ -229,7 +229,7 @@ When a filesystem supports both file handles and automount points, a .BR name_to_handle_at () call on an automount point will return with error -.BR EOVERFLOW +.B EOVERFLOW without having increased .IR handle_bytes . This can happen since Linux 4.13 @@ -247,10 +247,10 @@ a file handle returned by a previous call to .BR name_to_handle_at (). .PP The -.IR mount_fd +.I mount_fd argument is a file descriptor for any object (file, directory, etc.) in the mounted filesystem with respect to which -.IR handle +.I handle should be interpreted. The special value .B AT_FDCWD @@ -299,7 +299,7 @@ can fail with the following errors: .IR pathname , .IR mount_id , or -.IR handle +.I handle points outside your accessible address space. .TP .B EINVAL @@ -307,14 +307,14 @@ points outside your accessible address space. includes an invalid bit value. .TP .B EINVAL -.IR handle\->handle_bytes +.I handle\->handle_bytes is greater than .BR MAX_HANDLE_SZ . .TP .B ENOENT .I pathname is an empty string, but -.BR AT_EMPTY_PATH +.B AT_EMPTY_PATH was not specified in .IR flags . .TP @@ -325,7 +325,7 @@ does not refer to a directory, and it is not the case that both .I flags includes -.BR AT_EMPTY_PATH +.B AT_EMPTY_PATH and .I pathname is an empty string. @@ -347,17 +347,17 @@ is updated to indicate the required size for the handle. can fail with the following errors: .TP .B EBADF -.IR mount_fd +.I mount_fd is not an open file descriptor. .TP .B EFAULT -.IR handle +.I handle points outside your accessible address space. .TP .B EINVAL .I handle->handle_bytes is greater than -.BR MAX_HANDLE_SZ +.B MAX_HANDLE_SZ or is equal to zero. .TP .B ELOOP @@ -369,7 +369,7 @@ was not specified in .TP .B EPERM The caller does not have the -.BR CAP_DAC_READ_SEARCH +.B CAP_DAC_READ_SEARCH capability. .TP .B ESTALE @@ -419,7 +419,7 @@ a stateless fashion with respect to the files it serves. If .I pathname refers to a symbolic link and -.IR flags +.I flags does not specify .BR AT_SYMLINK_FOLLOW , then @@ -430,16 +430,16 @@ The process receiving the handle can later perform operations on the symbolic link by converting the handle to a file descriptor using .BR open_by_handle_at () with the -.BR O_PATH +.B O_PATH flag, and then passing the file descriptor as the -.IR dirfd +.I dirfd argument in system calls such as .BR readlinkat (2) and .BR fchownat (2). .SS Obtaining a persistent filesystem ID The mount IDs in -.IR /proc/self/mountinfo +.I /proc/self/mountinfo can be reused as filesystems are unmounted and mounted. Therefore, the mount ID returned by .BR name_to_handle_at () @@ -464,7 +464,7 @@ That process can then be reversed, using the UUID to look up the device name, and then obtaining the corresponding mount point, in order to produce the -.IR mount_fd +.I mount_fd argument used by .BR open_by_handle_at (). .SH EXAMPLE @@ -487,14 +487,14 @@ The program then employs .BR open_by_handle_at () to open the file using that handle. If an optional command-line argument is supplied, then the -.IR mount_fd +.I mount_fd argument for .BR open_by_handle_at () is obtained by opening the directory named in that argument. Otherwise, -.IR mount_fd +.I mount_fd is obtained by scanning -.IR /proc/self/mountinfo +.I /proc/self/mountinfo to find a record whose mount ID matches the mount ID read from standard input, and the mount directory specified in that record is opened. -- 2.20.1 -- Bjarni I. Gislason
