diff --git a/lib/libsys/mq_getfd_np.2 b/lib/libsys/mq_getfd_np.2 new file mode 100644 --- /dev/null +++ b/lib/libsys/mq_getfd_np.2 @@ -0,0 +1,118 @@ +.\"- +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2024 Rick Parrish +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(s), this list of conditions and the following disclaimer as +.\" the first lines of this file unmodified other than the possible +.\" addition of one or more copyright notices. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice(s), this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY +.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR +.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, +.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, +.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" Portions of this text are reprinted and reproduced in electronic form +.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- +.\" Portable Operating System Interface (POSIX), The Open Group Base +.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of +.\" Electrical and Electronics Engineers, Inc and The Open Group. In the +.\" event of any discrepancy between this version and the original IEEE and +.\" The Open Group Standard, the original IEEE and The Open Group Standard is +.\" the referee document. The original Standard can be obtained online at +.\" http://www.opengroup.org/unix/online.html. +.\" +.Dd February 19, 2024 +.Dt MQ_GETFD_NP 2 +.Os +.Sh NAME +.Nm mq_getfd_np +.Nd get a file descriptor on an open message queue descriptor +.Sh LIBRARY +.Lb librt +.Sh SYNOPSIS +.In mqueue.h +.Ft int +.Fn mq_getfd_np "mqd_t mqd" +.Sh DESCRIPTION +The +.Fn mq_getfd_np +system call retrieves the underlying file descriptor from the given message queue descriptor +returned from +.Xr mq_open 2 . +The file descriptor is used by other functions to refer to that message queue. +The +.Fa mqd +argument must be an open message queue descriptor. +.Sh NOTES +.Fx +implements retrieval or alteration of message queue attributes based on the file +descriptor. +The open file descriptor is inherited by a child after +.Xr fork 2 . +The file descriptor is closed in a new image after +.Xr exec 3 . +The +.Xr fstat 2 , +.Xr fchmod 2 , +and +.Xr fchown 2 +system calls are supported for the file descriptor. +.Pp +Do not call +.Xr close 2 +on the file descriptor. Instead, call +.Xr mq_close 2 +on the mqd_t descriptor returned by +.Xr mq_open 2 . +Do not use the file descriptor after calling +.Xr mq_close 2 . +At best, file operations on the file descriptor will fail with +.Xr errno 2 +set to EBADF (Bad file descriptor). +In the worst case, the descriptor may have been reused and now refers to a different +file or device. +The file descriptor is safe to use so long as the message queue descriptor +remains open. +.Pp +Please see +.Xr mqueuefs 5 +for instructions on loading the module or compiling the service into +the kernel. +.Sh RETURN VALUES +Upon successful completion, the function returns a file descriptor; otherwise, +an invalid file descriptor may be returned. +.Sh ERRORS +The +.Fn mq_getfd_np +system call does not return any errors but may cause SIGSEGV on an invalid +message queue descriptor. +.Sh SEE ALSO +.Xr mq_close 2 , +.Xr mq_getattr 2 , +.Xr mq_open 2 , +.Xr mq_receive 2 , +.Xr mq_send 2 , +.Xr mq_setattr 2 , +.Xr mq_timedreceive 3 , +.Xr mq_timedsend 3 , +.Xr mq_unlink 2 , +.Xr mqueuefs 5 +.Sh HISTORY +Support for mq_getfd_np first appeared in +.Fx 11.0 .