diff --git a/lib/libc/gen/exec.3 b/lib/libc/gen/exec.3 index 8f866e5ab321..ce289ebf502a 100644 --- a/lib/libc/gen/exec.3 +++ b/lib/libc/gen/exec.3 @@ -1,400 +1,400 @@ .\" Copyright (c) 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" 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, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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. .\" .Dd December 11, 2023 .Dt EXEC 3 .Os .Sh NAME .Nm execl , .Nm execlp , .Nm execle , .Nm exect , .Nm execv , .Nm execvp , .Nm execvpe , .Nm execvP .Nd execute a file .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Vt extern char **environ ; .Ft int .Fn execl "const char *path" "const char *arg" ... NULL .Ft int .Fn execlp "const char *file" "const char *arg" ... NULL .Ft int .Fn execle "const char *path" "const char *arg" ... NULL "char *const envp[]" .Fc .Ft int .Fn exect "const char *path" "char *const argv[]" "char *const envp[]" .Ft int .Fn execv "const char *path" "char *const argv[]" .Ft int .Fn execvp "const char *file" "char *const argv[]" .Ft int .Fn execvpe "const char *file" "char *const argv[]" "char *const envp[]" .Ft int .Fn execvP "const char *file" "const char *search_path" "char *const argv[]" .Sh DESCRIPTION The .Nm exec family of functions replaces the current process image with a new process image. The functions described in this manual page are front-ends for the function .Xr execve 2 . (See the manual page for .Xr execve 2 for detailed information about the replacement of the current process.) .Pp The initial argument for these functions is the pathname of a file which is to be executed. .Pp The .Fa "const char *arg" and subsequent ellipses in the .Fn execl , .Fn execlp , and .Fn execle functions can be thought of as .Em arg0 , .Em arg1 , \&..., .Em argn . Together they describe a list of one or more pointers to null-terminated strings that represent the argument list available to the executed program. The first argument, by convention, should point to the file name associated with the file being executed. The list of arguments .Em must be terminated by a .Dv NULL pointer. .Pp The .Fn exect , .Fn execv , .Fn execvp , .Fn execvpe , and .Fn execvP functions provide an array of pointers to null-terminated strings that represent the argument list available to the new program. The first argument, by convention, should point to the file name associated with the file being executed. The array of pointers .Sy must be terminated by a .Dv NULL pointer. .Pp The .Fn execle , .Fn exect , and .Fn execvpe functions also specify the environment of the executed process by following the .Dv NULL pointer that terminates the list of arguments in the argument list or the pointer to the argv array with an additional argument. This additional argument is an array of pointers to null-terminated strings and .Em must be terminated by a .Dv NULL pointer. The other functions take the environment for the new process image from the external variable .Va environ in the current process. .Pp Some of these functions have special semantics. .Pp The functions .Fn execlp , .Fn execvp , .Fn execvpe , and .Fn execvP will duplicate the actions of the shell in searching for an executable file if the specified file name does not contain a slash .Dq Li / character. For .Fn execlp and .Fn execvp , .Fn execvpe , search path is the path specified in the environment by .Dq Ev PATH variable. If this variable is not specified, the default path is set according to the .Dv _PATH_DEFPATH definition in .In paths.h , which is set to .Dq Ev /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin . For .Fn execvP , the search path is specified as an argument to the function. In addition, certain errors are treated specially. .Pp If an error is ambiguous (for simplicity, we shall consider all errors except .Er ENOEXEC as being ambiguous here, although only the critical error .Er EACCES is really ambiguous), then these functions will act as if they stat the file to determine whether the file exists and has suitable execute permissions. If it does, they will return immediately with the global variable .Va errno restored to the value set by .Fn execve . Otherwise, the search will be continued. If the search completes without performing a successful .Fn execve or terminating due to an error, these functions will return with the global variable .Va errno set to .Er EACCES or .Er ENOENT according to whether at least one file with suitable execute permissions was found. .Pp If the header of a file is not recognized (the attempted .Fn execve returned .Er ENOEXEC ) , these functions will execute the shell with the path of the file as its first argument. (If this attempt fails, no further searching is done.) .Pp The function .Fn exect executes a file with the program tracing facilities enabled (see .Xr ptrace 2 ) . .Sh RETURN VALUES If any of the .Fn exec functions returns, an error will have occurred. The return value is \-1, and the global variable .Va errno will be set to indicate the error. .Sh FILES .Bl -tag -width /bin/sh -compact .It Pa /bin/sh The shell. .El .Sh COMPATIBILITY Historically, the default path for the .Fn execlp and .Fn execvp functions was .Dq Pa :/bin:/usr/bin . This was changed to remove the current directory to enhance system security. .Pp The behavior of .Fn execlp and .Fn execvp when errors occur while attempting to execute the file is not quite historic practice, and has not traditionally been documented and is not specified by the .Tn POSIX standard. .Pp Traditionally, the functions .Fn execlp and .Fn execvp ignored all errors except for the ones described above and .Er ETXTBSY , upon which they retried after sleeping for several seconds, and .Er ENOMEM and .Er E2BIG , upon which they returned. They now return for .Er ETXTBSY , and determine existence and executability more carefully. In particular, .Er EACCES for inaccessible directories in the path prefix is no longer confused with .Er EACCES for files with unsuitable execute permissions. In .Bx 4.4 , they returned upon all errors except .Er EACCES , .Er ENOENT , .Er ENOEXEC and .Er ETXTBSY . This was inferior to the traditional error handling, since it breaks the ignoring of errors for path prefixes and only improves the handling of the unusual ambiguous error .Er EFAULT and the unusual error .Er EIO . The behaviour was changed to match the behaviour of .Xr sh 1 . .Sh ERRORS The .Fn execl , .Fn execle , .Fn execlp , .Fn execvp , .Fn execvpe , and .Fn execvP functions may fail and set .Va errno for any of the errors specified for the library functions .Xr execve 2 and .Xr malloc 3 . .Pp The .Fn exect and .Fn execv functions may fail and set .Va errno for any of the errors specified for the library function .Xr execve 2 . .Sh SEE ALSO .Xr sh 1 , .Xr execve 2 , .Xr fork 2 , .Xr ktrace 2 , .Xr ptrace 2 , .Xr environ 7 .Sh STANDARDS The .Fn execl , .Fn execv , .Fn execle , .Fn execlp and .Fn execvp functions conform to .St -p1003.1-88 . The .Fn execvpe function is a GNU extension. .Sh HISTORY The .Fn exec function appeared in .At v1 . The .Fn execl and .Fn execv functions appeared in .At v2 . The .Fn execlp , .Fn execle , .Fn execve , and .Fn execvp functions appeared in .At v7 . The .Fn execvP function first appeared in .Fx 5.2 . The .Fn execvpe function first appeared in -.Fx 15.0 . +.Fx 14.1 . .Sh BUGS The type of the .Fa argv and .Fa envp parameters to .Fn execle , .Fn exect , .Fn execv , .Fn execvp , .Fn execvpe , and .Fn execvP is a historical accident and no sane implementation should modify the provided strings. The bogus parameter types trigger false positives from .Li const correctness analyzers. On .Fx , the .Fn __DECONST macro may be used to work around this limitation. .Pp Due to a fluke of the C standard, on platforms other than .Fx the definition of .Dv NULL may be the untyped number zero, rather than a .Ad (void *)0 expression. To distinguish the concepts, they are referred to as a .Dq null pointer constant and a .Dq null pointer , respectively. On exotic computer architectures that .Fx does not support, the null pointer constant and null pointer may have a different representation. In general, where this document and others reference a .Dv NULL value, they actually imply a null pointer. E.g., for portability to non-FreeBSD operating systems on exotic computer architectures, one may use .Li (char *)NULL in place of .Dv NULL when invoking .Fn execl , .Fn execle , and .Fn execlp . diff --git a/usr.bin/posixmqcontrol/posixmqcontrol.1 b/usr.bin/posixmqcontrol/posixmqcontrol.1 index 67ddbfd5eaf0..ec7059b90235 100644 --- a/usr.bin/posixmqcontrol/posixmqcontrol.1 +++ b/usr.bin/posixmqcontrol/posixmqcontrol.1 @@ -1,180 +1,180 @@ .\"- .\" 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, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, 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 AUTHORS AND CONTRIBUTORS ``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 AUTHORS OR CONTRIBUTORS 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. .\" .Dd February 19, 2024 .Dt POSIXMQCONTROL 1 .Os .Sh NAME .Nm posixmqcontrol .Nd Control POSIX mqueuefs message queues .Sh SYNOPSIS .Nm .Ar create .Fl q Ar queue .Fl s Ar size .Fl d Ar depth .Op Fl m Ar mode .Op Fl g Ar group .Op Fl u Ar user .Nm .Ar info .Fl q Ar queue .Nm .Ar recv .Fl q Ar queue .Nm .Ar rm .Fl q Ar queue .Nm .Ar send .Fl q Ar queue .Fl c Ar content .Op Fl p Ar priority .Sh DESCRIPTION The .Nm command allows separating POSIX message queue administration from application stack. Defining and adjusting queue attributes can be done without touching application code. It allows creating queues, inspecting queue metadata, altering group and user access to queues, dumping queue contents, and unlinking queues. .Pp Unlinking removes the name from the system and frees underlying memory. .Pp The maximum message size, maximum queue size, and current queue size are displayed by the .Ic info subcommand. This output is similar to running .Ic cat on a mqueuefs queue mounted under a mount point. This utility requires the .Ic mqueuefs kernel module to be loaded but does not require .Ic mqueuefs to be mounted as a file system. .Pp The following subcommands are provided: .Bl -tag -width truncate .It Ic create Create the named queues, if they do not already exist. More than one queue name may be created. The same maximum queue depth and maximum message size are used to create all queues. If a queue exists, then depth and size are optional. .Pp The required .Ar size and .Ar depth arguments specify the maximum message size (bytes per message) and maximum queue size (depth or number of messages in the queue). The optional numerical .Ar mode argument specifies the initial access mode. If the queue exists but does not match the requested size and depth, this utility will attempt to recreate the queue by first unlinking and then creating it. This will fail if the queue is not empty or is opened by other processes. .It Ic rm Unlink the queues specified - one attempt per queue. Failure to unlink one queue does not stop this sub-command from attempting to unlink the others. .It Ic info For each named queue, dispay the maximum message size, maximum queue size, current queue depth, user owner id, group owner id, and mode permission bits. .It Ic recv Wait for a message from a single named queue and display the message to standard output. .It Ic send Send messages to one or more named queues. If multiple messages and multiple queues are specified, the utility attempts to send all messages to all queues. The optional -p priority, if omitted, defaults to MQ_PRIO_MAX / 2 or medium priority. .El .Sh NOTES A change of queue geometry (maximum message size and/or maximum number of messages) requires destroying and re-creating the queue. As a safety feature, the create subcommand refuses to destroy a non-empty queue. If you use the rm subcommand to destroy a queue, any queued messages are lost. To avoid down-time when altering queue attributes, consider creating a new queue and configure reading applications to drain both new and old queues. Retire the old queue once all writers have been updated to write to the new queue. .Sh EXIT STATUS .Ex -std .Bl -bullet .It EX_NOTAVAILABLE usually means the mqueuefs kernel module is not loaded. .It EX_USAGE reports one or more incorrect parameters. .El .Sh EXAMPLES .Bl -bullet .It To retrieve the current message from a named queue, .Pa /1 , use the command .Dl "posixmqcontrol recv -q /1" .It To create a queue with the name .Pa /2 with maximum message size 100 and maximum queue depth 10, use the command .Dl "posixmqcontrol create -q /2 -s 100 -d 10" .It To send a message to a queue with the name .Pa /3 use the command .Dl "posixmqcontrol send -q /3 -c 'some choice words.'" .It To examine attributes of a queue named .Pa /4 use the command .Dl "posixmqcontrol info -q /4" .El .Sh SEE ALSO .Xr mq_open 2 , .Xr mq_getattr 2 , .Xr mq_receive 2 , .Xr mq_send 2 , .Xr mq_setattr 2 , .Xr mq_unlink 2 , .Xr mqueuefs 4 .Sh BUGS mq_timedsend and mq_timedrecv are not implemented. info reports a worst-case estimate for QSIZE. .Sh HISTORY The .Nm command appeared in -.Fx 15.0 . +.Fx 14.1 . .Sh AUTHORS The .Nm command and this manual page were written by .An Rick Parrish Aq Mt unitrunker@unitrunker.net.