Index: head/lib/libc/gen/cap_rights_get.3 =================================================================== --- head/lib/libc/gen/cap_rights_get.3 (revision 276005) +++ head/lib/libc/gen/cap_rights_get.3 (revision 276006) @@ -1,119 +1,119 @@ .\" .\" Copyright (c) 2013 The FreeBSD Foundation .\" All rights reserved. .\" .\" This documentation was written by Pawel Jakub Dawidek under sponsorship .\" from the FreeBSD Foundation. .\" .\" 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 AUTHOR 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 AUTHOR 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. .\" .\" $FreeBSD$ .\" .Dd March 27, 2014 .Dt CAP_RIGHTS_GET 3 .Os .Sh NAME .Nm cap_rights_get .Nd obtain capability rights .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/capsicum.h .Ft int .Fn cap_rights_get "int fd" "cap_rights_t *rights" .Sh DESCRIPTION The .Nm cap_rights_get function allows to obtain current capability rights for the given descriptor. The function will fill the .Fa rights argument with all capability rights if they were not limited or capability rights configured during the last successful call of .Xr cap_rights_limit 2 on the given descriptor. .Pp The .Fa rights argument can be inspected using .Xr cap_rights_init 3 family of functions. .Pp The complete list of the capability rights can be found in the .Xr rights 4 manual page. .Sh RETURN VALUES .Rv -std .Sh EXAMPLES The following example demonstrates how to limit file descriptor capability rights and how to obtain them. .Bd -literal cap_rights_t setrights, getrights; int fd; memset(&setrights, 0, sizeof(setrights)); memset(&getrights, 0, sizeof(getrights)); fd = open("/tmp/foo", O_RDONLY); if (fd < 0) err(1, "open() failed"); cap_rights_init(&setrights, CAP_FSTAT, CAP_READ); if (cap_rights_limit(fd, &setrights) < 0 && errno != ENOSYS) err(1, "cap_rights_limit() failed"); if (cap_rights_get(fd, &getrights) < 0 && errno != ENOSYS) err(1, "cap_rights_get() failed"); assert(memcmp(&setrights, &getrights, sizeof(setrights)) == 0); .Ed .Sh ERRORS .Fn cap_rights_get succeeds unless: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument is not a valid active descriptor. .It Bq Er EFAULT The .Fa rights argument points at an invalid address. .El .Sh SEE ALSO .Xr cap_rights_limit 2 , -.Xr cap_rights_init 3 , .Xr errno 2 , .Xr open 2 , .Xr assert 3 , +.Xr cap_rights_init 3 , .Xr err 3 , .Xr memcmp 3 , .Xr memset 3 , .Xr capsicum 4 , .Xr rights 4 .Sh HISTORY Support for capabilities and capabilities mode was developed as part of the .Tn TrustedBSD Project. .Sh AUTHORS This function was created by .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net under sponsorship of the FreeBSD Foundation. Index: head/lib/libc/gen/ftok.3 =================================================================== --- head/lib/libc/gen/ftok.3 (revision 276005) +++ head/lib/libc/gen/ftok.3 (revision 276006) @@ -1,83 +1,83 @@ .\" Copyright (c) 1994 SigmaSoft, Th. Lockert .\" 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. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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. .\" .\" $FreeBSD$ .Dd July 9, 2009 .Dt FTOK 3 .Os .Sh NAME .Nm ftok .Nd create IPC identifier from path name .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/ipc.h .Ft key_t .Fn ftok "const char *path" "int id" .Sh DESCRIPTION The .Fn ftok function attempts to create a unique key suitable for use with the .Xr msgget 2 , .Xr semget 2 and .Xr shmget 2 functions given the .Fa path of an existing file and a user-selectable .Fa id . .Pp The specified .Fa path must specify an existing file that is accessible to the calling process or the call will fail. Also, note that links to files will return the same key, given the same .Fa id . .Sh RETURN VALUES The .Fn ftok function will return -1 if .Fa path does not exist or if it cannot be accessed by the calling process. .Sh SEE ALSO +.Xr msgget 2 , .Xr semget 2 , -.Xr shmget 2 , -.Xr msgget 2 +.Xr shmget 2 .Sh HISTORY The .Fn ftok function originates with System V and is typically used by programs that use the System V IPC routines. .Sh AUTHORS .An Thorsten Lockert Aq Mt tholo@sigmasoft.com .Sh BUGS The returned key is computed based on the device minor number and inode of the specified .Fa path in combination with the lower 8 bits of the given .Fa id . Thus it is quite possible for the routine to return duplicate keys. Index: head/lib/libc/gen/ftw.3 =================================================================== --- head/lib/libc/gen/ftw.3 (revision 276005) +++ head/lib/libc/gen/ftw.3 (revision 276006) @@ -1,216 +1,218 @@ .\" $OpenBSD: ftw.3,v 1.5 2004/01/25 14:48:32 jmc Exp $ .\" .\" Copyright (c) 2003 Todd C. Miller .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .\" Sponsored in part by the Defense Advanced Research Projects .\" Agency (DARPA) and Air Force Research Laboratory, Air Force .\" Materiel Command, USAF, under agreement number F39502-99-1-0512. .\" .\" $FreeBSD$ .\" .Dd July 5, 2004 .Dt FTW 3 .Os .Sh NAME .Nm ftw , nftw .Nd traverse (walk) a file tree .Sh SYNOPSIS .In ftw.h .Ft int .Fo ftw .Fa "const char *path" .Fa "int \*[lp]*fn\*[rp]\*[lp]const char *, const struct stat *, int\*[rp]" .Fa "int maxfds" .Fc .Ft int .Fo nftw .Fa "const char *path" .Fa "int \*[lp]*fn\*[rp]\*[lp]const char *, const struct stat *, int, struct FTW *\*[rp]" .Fa "int maxfds" .Fa "int flags" .Fc .Sh DESCRIPTION The .Fn ftw and .Fn nftw functions traverse (walk) the directory hierarchy rooted in .Fa path . For each object in the hierarchy, these functions call the function pointed to by .Fa fn . The .Fn ftw function passes this function a pointer to a .Dv NUL Ns -terminated string containing the name of the object, a pointer to a .Vt stat structure corresponding to the object, and an integer flag. The .Fn nftw function passes the aforementioned arguments plus a pointer to a .Vt FTW structure as defined by .In ftw.h (shown below): .Bd -literal struct FTW { int base; /* offset of basename into pathname */ int level; /* directory depth relative to starting point */ }; .Ed .Pp Possible values for the flag passed to .Fa fn are: .Bl -tag -width ".Dv FTW_DNR" .It Dv FTW_F A regular file. .It Dv FTW_D A directory being visited in pre-order. .It Dv FTW_DNR A directory which cannot be read. The directory will not be descended into. .It Dv FTW_DP A directory being visited in post-order -.Fn ( nftw -only). +.Po Fn nftw +only +.Pc . .It Dv FTW_NS A file for which no .Xr stat 2 information was available. The contents of the .Vt stat structure are undefined. .It Dv FTW_SL A symbolic link. .It Dv FTW_SLN A symbolic link with a non-existent target -.Fn ( nftw -only). +.Po Fn nftw +only +.Pc . .El .Pp The .Fn ftw function traverses the tree in pre-order. That is, it processes the directory before the directory's contents. .Pp The .Fa maxfds argument specifies the maximum number of file descriptors to keep open while traversing the tree. It has no effect in this implementation. .Pp The .Fn nftw function has an additional .Fa flags argument with the following possible values: .Bl -tag -width ".Dv FTW_MOUNT" .It Dv FTW_PHYS Physical walk, do not follow symbolic links. .It Dv FTW_MOUNT The walk will not cross a mount point. .It FTW_DEPTH Process directories in post-order. Contents of a directory are visited before the directory itself. By default, .Fn nftw traverses the tree in pre-order. .It FTW_CHDIR Change to a directory before reading it. By default, .Fn nftw will change its starting directory. The current working directory will be restored to its original value before .Fn nftw returns. .El .Sh RETURN VALUES If the tree was traversed successfully, the .Fn ftw and .Fn nftw functions return 0. If the function pointed to by .Fa fn returns a non-zero value, .Fn ftw and .Fn nftw will stop processing the tree and return the value from .Fa fn . Both functions return \-1 if an error is detected. .Sh ERRORS The .Fn ftw and .Fn nftw functions may fail and set .Va errno for any of the errors specified for the library functions .Xr close 2 , .Xr open 2 , .Xr stat 2 , .Xr malloc 3 , .Xr opendir 3 and .Xr readdir 3 . If the .Dv FTW_CHDIR flag is set, the .Fn nftw function may fail and set .Va errno for any of the errors specified for .Xr chdir 2 . In addition, either function may fail and set .Va errno as follows: .Bl -tag -width Er .It Bq Er EINVAL The .Fa maxfds argument is less than 1. .El .Sh SEE ALSO .Xr chdir 2 , .Xr close 2 , .Xr open 2 , .Xr stat 2 , .Xr fts 3 , .Xr malloc 3 , .Xr opendir 3 , .Xr readdir 3 .Sh STANDARDS The .Fn ftw and .Fn nftw functions conform to .St -p1003.1-2001 . .Sh HISTORY These functions first appeared in .At V.3 . Their first .Fx appearance was in .Fx 5.3 . .Sh BUGS The .Fa maxfds argument is currently ignored. Index: head/lib/libc/gen/getcap.3 =================================================================== --- head/lib/libc/gen/getcap.3 (revision 276005) +++ head/lib/libc/gen/getcap.3 (revision 276006) @@ -1,568 +1,569 @@ .\" Copyright (c) 1992, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Casey Leedom of Lawrence Livermore National Laboratory. .\" .\" 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. .\" 4. 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. .\" .\" @(#)getcap.3 8.4 (Berkeley) 5/13/94 .\" $FreeBSD$ .\" .Dd March 22, 2002 .Dt GETCAP 3 .Os .Sh NAME .Nm cgetent , .Nm cgetset , .Nm cgetmatch , .Nm cgetcap , .Nm cgetnum , .Nm cgetstr , .Nm cgetustr , .Nm cgetfirst , .Nm cgetnext , .Nm cgetclose .Nd capability database access routines .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In stdlib.h .Ft int .Fn cgetent "char **buf" "char **db_array" "const char *name" .Ft int .Fn cgetset "const char *ent" .Ft int .Fn cgetmatch "const char *buf" "const char *name" .Ft char * .Fn cgetcap "char *buf" "const char *cap" "int type" .Ft int .Fn cgetnum "char *buf" "const char *cap" "long *num" .Ft int .Fn cgetstr "char *buf" "const char *cap" "char **str" .Ft int .Fn cgetustr "char *buf" "const char *cap" "char **str" .Ft int .Fn cgetfirst "char **buf" "char **db_array" .Ft int .Fn cgetnext "char **buf" "char **db_array" .Ft int .Fn cgetclose "void" .Sh DESCRIPTION The .Fn cgetent function extracts the capability .Fa name from the database specified by the .Dv NULL terminated file array .Fa db_array and returns a pointer to a .Xr malloc 3 Ns \&'d copy of it in .Fa buf . The .Fn cgetent function will first look for files ending in .Pa .db (see .Xr cap_mkdb 1 ) before accessing the ASCII file. The .Fa buf argument must be retained through all subsequent calls to .Fn cgetmatch , .Fn cgetcap , .Fn cgetnum , .Fn cgetstr , and .Fn cgetustr , but may then be .Xr free 3 Ns \&'d . On success 0 is returned, 1 if the returned record contains an unresolved .Ic tc expansion, \-1 if the requested record could not be found, \-2 if a system error was encountered (could not open/read a file, etc.) also setting .Va errno , and \-3 if a potential reference loop is detected (see .Ic tc= comments below). .Pp The .Fn cgetset function enables the addition of a character buffer containing a single capability record entry to the capability database. Conceptually, the entry is added as the first ``file'' in the database, and is therefore searched first on the call to .Fn cgetent . The entry is passed in .Fa ent . If .Fa ent is .Dv NULL , the current entry is removed from the database. A call to .Fn cgetset must precede the database traversal. It must be called before the .Fn cgetent call. If a sequential access is being performed (see below), it must be called before the first sequential access call -.Fn ( cgetfirst +.Po Fn cgetfirst or -.Fn cgetnext ) , +.Fn cgetnext +.Pc , or be directly preceded by a .Fn cgetclose call. On success 0 is returned and \-1 on failure. .Pp The .Fn cgetmatch function will return 0 if .Fa name is one of the names of the capability record .Fa buf , \-1 if not. .Pp The .Fn cgetcap function searches the capability record .Fa buf for the capability .Fa cap with type .Fa type . A .Fa type is specified using any single character. If a colon (`:') is used, an untyped capability will be searched for (see below for explanation of types). A pointer to the value of .Fa cap in .Fa buf is returned on success, .Dv NULL if the requested capability could not be found. The end of the capability value is signaled by a `:' or .Tn ASCII .Dv NUL (see below for capability database syntax). .Pp The .Fn cgetnum function retrieves the value of the numeric capability .Fa cap from the capability record pointed to by .Fa buf . The numeric value is returned in the .Ft long pointed to by .Fa num . 0 is returned on success, \-1 if the requested numeric capability could not be found. .Pp The .Fn cgetstr function retrieves the value of the string capability .Fa cap from the capability record pointed to by .Fa buf . A pointer to a decoded, .Dv NUL terminated, .Xr malloc 3 Ns \&'d copy of the string is returned in the .Ft char * pointed to by .Fa str . The number of characters in the decoded string not including the trailing .Dv NUL is returned on success, \-1 if the requested string capability could not be found, \-2 if a system error was encountered (storage allocation failure). .Pp The .Fn cgetustr function is identical to .Fn cgetstr except that it does not expand special characters, but rather returns each character of the capability string literally. .Pp The .Fn cgetfirst and .Fn cgetnext functions comprise a function group that provides for sequential access of the .Dv NULL pointer terminated array of file names, .Fa db_array . The .Fn cgetfirst function returns the first record in the database and resets the access to the first record. The .Fn cgetnext function returns the next record in the database with respect to the record returned by the previous .Fn cgetfirst or .Fn cgetnext call. If there is no such previous call, the first record in the database is returned. Each record is returned in a .Xr malloc 3 Ns \&'d copy pointed to by .Fa buf . .Ic Tc expansion is done (see .Ic tc= comments below). Upon completion of the database 0 is returned, 1 is returned upon successful return of record with possibly more remaining (we have not reached the end of the database yet), 2 is returned if the record contains an unresolved .Ic tc expansion, \-1 is returned if a system error occurred, and \-2 is returned if a potential reference loop is detected (see .Ic tc= comments below). Upon completion of database (0 return) the database is closed. .Pp The .Fn cgetclose function closes the sequential access and frees any memory and file descriptors being used. Note that it does not erase the buffer pushed by a call to .Fn cgetset . .Sh CAPABILITY DATABASE SYNTAX Capability databases are normally .Tn ASCII and may be edited with standard text editors. Blank lines and lines beginning with a `#' are comments and are ignored. Lines ending with a `\|\e' indicate that the next line is a continuation of the current line; the `\|\e' and following newline are ignored. Long lines are usually continued onto several physical lines by ending each line except the last with a `\|\e'. .Pp Capability databases consist of a series of records, one per logical line. Each record contains a variable number of `:'-separated fields (capabilities). Empty fields consisting entirely of white space characters (spaces and tabs) are ignored. .Pp The first capability of each record specifies its names, separated by `|' characters. These names are used to reference records in the database. By convention, the last name is usually a comment and is not intended as a lookup tag. For example, the .Em vt100 record from the .Xr termcap 5 database begins: .Pp .Dl "d0\||\|vt100\||\|vt100-am\||\|vt100am\||\|dec vt100:" .Pp giving four names that can be used to access the record. .Pp The remaining non-empty capabilities describe a set of (name, value) bindings, consisting of a names optionally followed by a typed value: .Pp .Bl -tag -width "nameTvalue" -compact .It name typeless [boolean] capability .Em name No "is present [true]" .It name Ns Em \&T Ns value capability .Pq Em name , \&T has value .Em value .It name@ no capability .Em name No exists .It name Ns Em T Ns \&@ capability .Pq Em name , T does not exist .El .Pp Names consist of one or more characters. Names may contain any character except `:', but it is usually best to restrict them to the printable characters and avoid use of graphics like `#', `=', `%', `@', etc. Types are single characters used to separate capability names from their associated typed values. Types may be any character except a `:'. Typically, graphics like `#', `=', `%', etc.\& are used. Values may be any number of characters and may contain any character except `:'. .Sh CAPABILITY DATABASE SEMANTICS Capability records describe a set of (name, value) bindings. Names may have multiple values bound to them. Different values for a name are distinguished by their .Fa types . The .Fn cgetcap function will return a pointer to a value of a name given the capability name and the type of the value. .Pp The types `#' and `=' are conventionally used to denote numeric and string typed values, but no restriction on those types is enforced. The functions .Fn cgetnum and .Fn cgetstr can be used to implement the traditional syntax and semantics of `#' and `='. Typeless capabilities are typically used to denote boolean objects with presence or absence indicating truth and false values respectively. This interpretation is conveniently represented by: .Pp .Dl "(getcap(buf, name, ':') != NULL)" .Pp A special capability, .Ic tc= name , is used to indicate that the record specified by .Fa name should be substituted for the .Ic tc capability. .Ic Tc capabilities may interpolate records which also contain .Ic tc capabilities and more than one .Ic tc capability may be used in a record. A .Ic tc expansion scope (i.e., where the argument is searched for) contains the file in which the .Ic tc is declared and all subsequent files in the file array. .Pp When a database is searched for a capability record, the first matching record in the search is returned. When a record is scanned for a capability, the first matching capability is returned; the capability .Ic :nameT@: will hide any following definition of a value of type .Em T for .Fa name ; and the capability .Ic :name@: will prevent any following values of .Fa name from being seen. .Pp These features combined with .Ic tc capabilities can be used to generate variations of other databases and records by either adding new capabilities, overriding definitions with new definitions, or hiding following definitions via `@' capabilities. .Sh EXAMPLES .Bd -unfilled -offset indent example\||\|an example of binding multiple values to names:\e :foo%bar:foo^blah:foo@:\e :abc%xyz:abc^frap:abc$@:\e :tc=more: .Ed .Pp The capability foo has two values bound to it (bar of type `%' and blah of type `^') and any other value bindings are hidden. The capability abc also has two values bound but only a value of type `$' is prevented from being defined in the capability record more. .Bd -unfilled -offset indent file1: new\||\|new_record\||\|a modification of "old":\e :fript=bar:who-cares@:tc=old:blah:tc=extensions: file2: old\||\|old_record\||\|an old database record:\e :fript=foo:who-cares:glork#200: .Ed .Pp The records are extracted by calling .Fn cgetent with file1 preceding file2. In the capability record new in file1, fript=bar overrides the definition of fript=foo interpolated from the capability record old in file2, who-cares@ prevents the definition of any who-cares definitions in old from being seen, glork#200 is inherited from old, and blah and anything defined by the record extensions is added to those definitions in old. Note that the position of the fript=bar and who-cares@ definitions before tc=old is important here. If they were after, the definitions in old would take precedence. .Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS Two types are predefined by .Fn cgetnum and .Fn cgetstr : .Pp .Bl -tag -width "nameXnumber" -compact .It Em name Ns \&# Ns Em number numeric capability .Em name has value .Em number .It Em name Ns = Ns Em string string capability .Em name has value .Em string .It Em name Ns \&#@ the numeric capability .Em name does not exist .It Em name Ns \&=@ the string capability .Em name does not exist .El .Pp Numeric capability values may be given in one of three numeric bases. If the number starts with either .Ql 0x or .Ql 0X it is interpreted as a hexadecimal number (both upper and lower case a-f may be used to denote the extended hexadecimal digits). Otherwise, if the number starts with a .Ql 0 it is interpreted as an octal number. Otherwise the number is interpreted as a decimal number. .Pp String capability values may contain any character. Non-printable .Dv ASCII codes, new lines, and colons may be conveniently represented by the use of escape sequences: .Bl -column "\e\|X,X\e\|X" "(ASCII octal nnn)" ^X ('X' & 037) control-X \e\|b, \e\|B (ASCII 010) backspace \e\|t, \e\|T (ASCII 011) tab \e\|n, \e\|N (ASCII 012) line feed (newline) \e\|f, \e\|F (ASCII 014) form feed \e\|r, \e\|R (ASCII 015) carriage return \e\|e, \e\|E (ASCII 027) escape \e\|c, \e\|C (:) colon \e\|\e (\e\|) back slash \e\|^ (^) caret \e\|nnn (ASCII octal nnn) .El .Pp A `\|\e' may be followed by up to three octal digits directly specifies the numeric code for a character. The use of .Tn ASCII .Dv NUL Ns s , while easily encoded, causes all sorts of problems and must be used with care since .Dv NUL Ns s are typically used to denote the end of strings; many applications use `\e\|200' to represent a .Dv NUL . .Sh DIAGNOSTICS The .Fn cgetent , .Fn cgetset , .Fn cgetmatch , .Fn cgetnum , .Fn cgetstr , .Fn cgetustr , .Fn cgetfirst , and .Fn cgetnext functions return a value greater than or equal to 0 on success and a value less than 0 on failure. The .Fn cgetcap function returns a character pointer on success and a .Dv NULL on failure. .Pp The .Fn cgetent , and .Fn cgetset functions may fail and set .Va errno for any of the errors specified for the library functions: .Xr fopen 3 , .Xr fclose 3 , .Xr open 2 , and .Xr close 2 . .Pp The .Fn cgetent , .Fn cgetset , .Fn cgetstr , and .Fn cgetustr functions may fail and set .Va errno as follows: .Bl -tag -width Er .It Bq Er ENOMEM No memory to allocate. .El .Sh SEE ALSO .Xr cap_mkdb 1 , .Xr malloc 3 .Sh BUGS Colons (`:') cannot be used in names, types, or values. .Pp There are no checks for .Ic tc Ns = Ns Ic name loops in .Fn cgetent . .Pp The buffer added to the database by a call to .Fn cgetset is not unique to the database but is rather prepended to any database used. Index: head/lib/libc/gen/posix_spawn.3 =================================================================== --- head/lib/libc/gen/posix_spawn.3 (revision 276005) +++ head/lib/libc/gen/posix_spawn.3 (revision 276006) @@ -1,460 +1,460 @@ .\" Copyright (c) 2008 Ed Schouten .\" 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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. .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd June 17, 2011 .Dt POSIX_SPAWN 3 .Os .Sh NAME .Nm posix_spawn , .Nm posix_spawnp .Nd "spawn a process" .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In spawn.h .Ft int .Fn posix_spawn "pid_t *restrict pid" "const char *restrict path" "const posix_spawn_file_actions_t *file_actions" "const posix_spawnattr_t *restrict attrp" "char *const argv[restrict]" "char *const envp[restrict]" .Ft int .Fn posix_spawnp "pid_t *restrict pid" "const char *restrict file" "const posix_spawn_file_actions_t *file_actions" "const posix_spawnattr_t *restrict attrp" "char *const argv[restrict]" "char *const envp[restrict]" .Sh DESCRIPTION The .Fn posix_spawn and .Fn posix_spawnp functions create a new process (child process) from the specified process image. The new process image is constructed from a regular executable file called the new process image file. .Pp When a C program is executed as the result of this call, it is entered as a C-language function call as follows: .Bd -literal -offset indent int main(int argc, char *argv[]); .Ed .Pp where .Fa argc is the argument count and .Fa argv is an array of character pointers to the arguments themselves. In addition, the variable: .Bd -literal -offset indent extern char **environ; .Ed .Pp points to an array of character pointers to the environment strings. .Pp The argument .Fa argv is an array of character pointers to null-terminated strings. The last member of this array is a null pointer and is not counted in .Fa argc . These strings constitute the argument list available to the new process image. The value in .Fa argv Ns [0] should point to a filename that is associated with the process image being started by the .Fn posix_spawn or .Fn posix_spawnp function. .Pp The argument .Fa envp is an array of character pointers to null-terminated strings. These strings constitute the environment for the new process image. The environment array is terminated by a null pointer. .Pp The .Fa path argument to .Fn posix_spawn is a pathname that identifies the new process image file to execute. .Pp The .Fa file parameter to .Fn posix_spawnp is used to construct a pathname that identifies the new process image file. If the file parameter contains a slash character, the file parameter is used as the pathname for the new process image file. Otherwise, the path prefix for this file is obtained by a search of the directories passed as the environment variable .Dq Ev PATH . 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 /usr/bin:/bin . .Pp If .Fa file_actions is a null pointer, then file descriptors open in the calling process remain open in the child process, except for those whose close-on-exec flag .Dv FD_CLOEXEC is set (see .Fn fcntl ) . For those file descriptors that remain open, all attributes of the corresponding open file descriptions, including file locks (see .Fn fcntl ) , remain unchanged. .Pp If .Fa file_actions is not NULL, then the file descriptors open in the child process are those open in the calling process as modified by the spawn file actions object pointed to by .Fa file_actions and the .Dv FD_CLOEXEC flag of each remaining open file descriptor after the spawn file actions have been processed. The effective order of processing the spawn file actions are: .Bl -enum .It The set of open file descriptors for the child process initially are the same set as is open for the calling process. All attributes of the corresponding open file descriptions, including file locks (see .Fn fcntl ) , remain unchanged. .It The signal mask, signal default actions, and the effective user and group IDs for the child process are changed as specified in the attributes object referenced by .Fa attrp . .It The file actions specified by the spawn file actions object are performed in the order in which they were added to the spawn file actions object. .It Any file descriptor that has its .Dv FD_CLOEXEC flag set (see .Fn fcntl ) is closed. .El .Pp The .Vt posix_spawnattr_t spawn attributes object type is defined in .In spawn.h . It contains the attributes defined below. .Pp If the .Dv POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute of the object referenced by .Fa attrp , and the spawn-pgroup attribute of the same object is non-zero, then the child's process group is as specified in the spawn-pgroup attribute of the object referenced by .Fa attrp . .Pp As a special case, if the .Dv POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute of the object referenced by .Fa attrp , and the spawn-pgroup attribute of the same object is set to zero, then the child is in a new process group with a process group ID equal to its process ID. .Pp If the .Dv POSIX_SPAWN_SETPGROUP flag is not set in the spawn-flags attribute of the object referenced by .Fa attrp , the new child process inherits the parent's process group. .Pp If the .Dv POSIX_SPAWN_SETSCHEDPARAM flag is set in the spawn-flags attribute of the object referenced by .Fa attrp , but .Dv POSIX_SPAWN_SETSCHEDULER is not set, the new process image initially has the scheduling policy of the calling process with the scheduling parameters specified in the spawn-schedparam attribute of the object referenced by .Fa attrp . .Pp If the .Dv POSIX_SPAWN_SETSCHEDULER flag is set in the spawn-flags attribute of the object referenced by .Fa attrp (regardless of the setting of the .Dv POSIX_SPAWN_SETSCHEDPARAM flag), the new process image initially has the scheduling policy specified in the spawn-schedpolicy attribute of the object referenced by .Fa attrp and the scheduling parameters specified in the spawn-schedparam attribute of the same object. .Pp The .Dv POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute of the object referenced by .Fa attrp governs the effective user ID of the child process. If this flag is not set, the child process inherits the parent process' effective user ID. If this flag is set, the child process' effective user ID is reset to the parent's real user ID. In either case, if the set-user-ID mode bit of the new process image file is set, the effective user ID of the child process becomes that file's owner ID before the new process image begins execution. .Pp The .Dv POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute of the object referenced by .Fa attrp also governs the effective group ID of the child process. If this flag is not set, the child process inherits the parent process' effective group ID. If this flag is set, the child process' effective group ID is reset to the parent's real group ID. In either case, if the set-group-ID mode bit of the new process image file is set, the effective group ID of the child process becomes that file's group ID before the new process image begins execution. .Pp If the .Dv POSIX_SPAWN_SETSIGMASK flag is set in the spawn-flags attribute of the object referenced by .Fa attrp , the child process initially has the signal mask specified in the spawn-sigmask attribute of the object referenced by .Fa attrp . .Pp If the .Dv POSIX_SPAWN_SETSIGDEF flag is set in the spawn-flags attribute of the object referenced by .Fa attrp , the signals specified in the spawn-sigdefault attribute of the same object is set to their default actions in the child process. Signals set to the default action in the parent process is set to the default action in the child process. .Pp Signals set to be caught by the calling process is set to the default action in the child process. .Pp Signals set to be ignored by the calling process image is set to be ignored by the child process, unless otherwise specified by the .Dv POSIX_SPAWN_SETSIGDEF flag being set in the spawn-flags attribute of the object referenced by .Fa attrp and the signals being indicated in the spawn-sigdefault attribute of the object referenced by .Fa attrp . .Pp If the value of the .Fa attrp pointer is NULL, then the default values are used. .Pp All process attributes, other than those influenced by the attributes set in the object referenced by .Fa attrp as specified above or by the file descriptor manipulations specified in .Fa file_actions , appear in the new process image as though .Fn vfork had been called to create a child process and then .Fn execve had been called by the child process to execute the new process image. .Pp The implementation uses vfork(), thus the fork handlers are not run when .Fn posix_spawn or .Fn posix_spawnp is called. .Sh RETURN VALUES Upon successful completion, .Fn posix_spawn and .Fn posix_spawnp return the process ID of the child process to the parent process, in the variable pointed to by a non-NULL .Fa pid argument, and return zero as the function return value. Otherwise, no child process is created, no value is stored into the variable pointed to by .Fa pid , and an error number is returned as the function return value to indicate the error. If the .Fa pid argument is a null pointer, the process ID of the child is not returned to the caller. .Sh ERRORS .Bl -enum .It If .Fn posix_spawn and .Fn posix_spawnp fail for any of the reasons that would cause .Fn vfork or one of the .Nm exec to fail, an error value is returned as described by .Fn vfork and .Nm exec , respectively (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127). .It If .Nm POSIX_SPAWN_SETPGROUP is set in the spawn-flags attribute of the object referenced by attrp, and .Fn posix_spawn or .Fn posix_spawnp fails while changing the child's process group, an error value is returned as described by .Fn setpgid (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127). .It If .Nm POSIX_SPAWN_SETSCHEDPARAM is set and .Nm POSIX_SPAWN_SETSCHEDULER is not set in the spawn-flags attribute of the object referenced by attrp, then if .Fn posix_spawn or .Fn posix_spawnp fails for any of the reasons that would cause .Fn sched_setparam to fail, an error value is returned as described by .Fn sched_setparam (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127). .It If .Nm POSIX_SPAWN_SETSCHEDULER is set in the spawn-flags attribute of the object referenced by attrp, and if .Fn posix_spawn or .Fn posix_spawnp fails for any of the reasons that would cause .Fn sched_setscheduler to fail, an error value is returned as described by .Fn sched_setscheduler (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127). .It If the .Fa file_actions argument is not NULL, and specifies any dup2 or open actions to be performed, and if .Fn posix_spawn or .Fn posix_spawnp fails for any of the reasons that would cause .Fn dup2 or .Fn open to fail, an error value is returned as described by .Fn dup2 and .Fn open , respectively (or, if the error occurs after the calling process successfully returns, the child process exits with exit status 127). An open file action may, by itself, result in any of the errors described by .Fn dup2 , in addition to those described by .Fn open . This implementation ignores any errors from .Fn close , including trying to close a descriptor that is not open. .El .Sh SEE ALSO .Xr close 2 , .Xr dup2 2 , .Xr execve 2 , .Xr fcntl 2 , .Xr open 2 , +.Xr sched_setparam 2 , +.Xr sched_setscheduler 2 , +.Xr setpgid 2 , +.Xr vfork 2 , .Xr posix_spawn_file_actions_addclose 3 , .Xr posix_spawn_file_actions_adddup2 3 , .Xr posix_spawn_file_actions_addopen 3 , .Xr posix_spawn_file_actions_destroy 3 , .Xr posix_spawn_file_actions_init 3 , .Xr posix_spawnattr_destroy 3 , .Xr posix_spawnattr_getflags 3 , .Xr posix_spawnattr_getpgroup 3 , .Xr posix_spawnattr_getschedparam 3 , .Xr posix_spawnattr_getschedpolicy 3 , .Xr posix_spawnattr_getsigdefault 3 , .Xr posix_spawnattr_getsigmask 3 , .Xr posix_spawnattr_init 3 , .Xr posix_spawnattr_setflags 3 , .Xr posix_spawnattr_setpgroup 3 , .Xr posix_spawnattr_setschedparam 3 , .Xr posix_spawnattr_setschedpolicy 3 , .Xr posix_spawnattr_setsigdefault 3 , -.Xr posix_spawnattr_setsigmask 3 , -.Xr sched_setparam 2 , -.Xr sched_setscheduler 2 , -.Xr setpgid 2 , -.Xr vfork 2 +.Xr posix_spawnattr_setsigmask 3 .Sh STANDARDS The .Fn posix_spawn and .Fn posix_spawnp functions conform to .St -p1003.1-2001 , except that they ignore all errors from .Fn close . A future update of the Standard is expected to require that these functions not fail because a file descriptor to be closed (via .Fn posix_spawn_file_actions_addclose ) is not open. .Sh HISTORY The .Fn posix_spawn and .Fn posix_spawnp functions first appeared in .Fx 8.0 . .Sh AUTHORS .An Ed Schouten Aq Mt ed@FreeBSD.org Index: head/lib/libc/gen/scandir.3 =================================================================== --- head/lib/libc/gen/scandir.3 (revision 276005) +++ head/lib/libc/gen/scandir.3 (revision 276006) @@ -1,117 +1,117 @@ .\" Copyright (c) 1983, 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. .\" 4. 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. .\" .\" @(#)scandir.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd January 3, 2010 .Dt SCANDIR 3 .Os .Sh NAME .Nm scandir , .Nm alphasort .Nd scan a directory .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In dirent.h .Ft int .Fn scandir "const char *dirname" "struct dirent ***namelist" "int \*(lp*select\*(rp\*(lpconst struct dirent *\*(rp" "int \*(lp*compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" .Ft int .Fn scandir_b "const char *dirname" "struct dirent ***namelist" "int \*(lp*select\^(rp\*(lpconst struct dirent *\*(rp" "int \*(lp^compar\*(rp\*(lpconst struct dirent **, const struct dirent **\*(rp" .Ft int .Fn alphasort "const struct dirent **d1" "const struct dirent **d2" .Sh DESCRIPTION The .Fn scandir function reads the directory .Fa dirname and builds an array of pointers to directory entries using .Xr malloc 3 . It returns the number of entries in the array. A pointer to the array of directory entries is stored in the location referenced by .Fa namelist . .Pp The .Fa select argument is a pointer to a user supplied subroutine which is called by .Fn scandir to select which entries are to be included in the array. The select routine is passed a pointer to a directory entry and should return a non-zero value if the directory entry is to be included in the array. If .Fa select is null, then all the directory entries will be included. .Pp The .Fa compar argument is a pointer to a user supplied subroutine which is passed to .Xr qsort 3 to sort the completed array. If this pointer is null, the array is not sorted. .Pp The .Fn alphasort function is a routine which can be used for the .Fa compar argument to sort the array alphabetically using .Xr strcoll 3 . .Pp The memory allocated for the array can be deallocated with .Xr free 3 , by freeing each pointer in the array and then the array itself. .Pp The .Fn scandir_b -function behaves in the same way as +function behaves in the same way as .Fn scandir , but takes blocks as arguments instead of function pointers and calls .Fn qsort_b rather than .Fn qsort . .Sh DIAGNOSTICS Returns \-1 if the directory cannot be opened for reading or if .Xr malloc 3 cannot allocate enough memory to hold all the data structures. .Sh SEE ALSO .Xr directory 3 , .Xr malloc 3 , .Xr qsort 3 , -.Xr dir 5 , -.Xr strcoll 3 +.Xr strcoll 3 , +.Xr dir 5 .Sh HISTORY The .Fn scandir and .Fn alphasort functions appeared in .Bx 4.2 . Index: head/lib/libc/net/getaddrinfo.3 =================================================================== --- head/lib/libc/net/getaddrinfo.3 (revision 276005) +++ head/lib/libc/net/getaddrinfo.3 (revision 276006) @@ -1,460 +1,460 @@ .\" $KAME: getaddrinfo.3,v 1.36 2005/01/05 03:23:05 itojun Exp $ .\" $OpenBSD: getaddrinfo.3,v 1.35 2004/12/21 03:40:31 jaredy Exp $ .\" .\" Copyright (C) 2004 Internet Systems Consortium, Inc. ("ISC") .\" Copyright (C) 2000, 2001 Internet Software Consortium. .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH .\" REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY .\" AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, .\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM .\" LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE .\" OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR .\" PERFORMANCE OF THIS SOFTWARE. .\" .\" $FreeBSD$ .\" .Dd February 14, 2013 .Dt GETADDRINFO 3 .Os .Sh NAME .Nm getaddrinfo , .Nm freeaddrinfo .Nd socket address structure to host and service name .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netdb.h .Ft int .Fo getaddrinfo .Fa "const char *hostname" "const char *servname" .Fa "const struct addrinfo *hints" "struct addrinfo **res" .Fc .Ft void .Fn freeaddrinfo "struct addrinfo *ai" .Sh DESCRIPTION The .Fn getaddrinfo function is used to get a list of .Tn IP addresses and port numbers for host .Fa hostname and service .Fa servname . It is a replacement for and provides more flexibility than the .Xr gethostbyname 3 and .Xr getservbyname 3 functions. .Pp The .Fa hostname and .Fa servname arguments are either pointers to NUL-terminated strings or the null pointer. An acceptable value for .Fa hostname is either a valid host name or a numeric host address string consisting of a dotted decimal IPv4 address or an IPv6 address. The .Fa servname is either a decimal port number or a service name listed in .Xr services 5 . At least one of .Fa hostname and .Fa servname must be non-null. .Pp .Fa hints is an optional pointer to a .Li struct addrinfo , as defined by .Aq Pa netdb.h : .Bd -literal struct addrinfo { int ai_flags; /* input flags */ int ai_family; /* protocol family for socket */ int ai_socktype; /* socket type */ int ai_protocol; /* protocol for socket */ socklen_t ai_addrlen; /* length of socket-address */ struct sockaddr *ai_addr; /* socket-address for socket */ char *ai_canonname; /* canonical name for service location */ struct addrinfo *ai_next; /* pointer to next in list */ }; .Ed .Pp This structure can be used to provide hints concerning the type of socket that the caller supports or wishes to use. The caller can supply the following structure elements in .Fa hints : .Bl -tag -width "ai_socktypeXX" .It Fa ai_family The protocol family that should be used. When .Fa ai_family is set to .Dv PF_UNSPEC , it means the caller will accept any protocol family supported by the operating system. .It Fa ai_socktype Denotes the type of socket that is wanted: .Dv SOCK_STREAM , .Dv SOCK_DGRAM , or .Dv SOCK_RAW . When .Fa ai_socktype is zero the caller will accept any socket type. .It Fa ai_protocol Indicates which transport protocol is desired, .Dv IPPROTO_UDP or .Dv IPPROTO_TCP . If .Fa ai_protocol is zero the caller will accept any protocol. .It Fa ai_flags The .Fa ai_flags field to which the .Fa hints parameter points shall be set to zero or be the bitwise-inclusive OR of one or more of the values .Dv AI_ADDRCONFIG , .Dv AI_CANONNAME , .Dv AI_NUMERICHOST , .Dv AI_NUMERICSERV and .Dv AI_PASSIVE . .Bl -tag -width "AI_CANONNAMEXX" .It Dv AI_ADDRCONFIG If the .Dv AI_ADDRCONFIG bit is set, IPv4 addresses shall be returned only if an IPv4 address is configured on the local system, and IPv6 addresses shall be returned only if an IPv6 address is configured on the local system. .It Dv AI_CANONNAME If the .Dv AI_CANONNAME bit is set, a successful call to .Fn getaddrinfo will return a NUL-terminated string containing the canonical name of the specified hostname in the .Fa ai_canonname element of the first .Li addrinfo structure returned. .It Dv AI_NUMERICHOST If the .Dv AI_NUMERICHOST bit is set, it indicates that .Fa hostname should be treated as a numeric string defining an IPv4 or IPv6 address and no name resolution should be attempted. .It Dv AI_NUMERICSERV If the .Dv AI_NUMERICSERV bit is set, then a non-null .Fa servname string supplied shall be a numeric port string. Otherwise, an .Dv EAI_NONAME error shall be returned. This bit shall prevent any type of name resolution service (for example, NIS+) from being invoked. .It Dv AI_PASSIVE If the .Dv AI_PASSIVE bit is set it indicates that the returned socket address structure is intended for use in a call to .Xr bind 2 . In this case, if the .Fa hostname argument is the null pointer, then the IP address portion of the socket address structure will be set to .Dv INADDR_ANY for an IPv4 address or .Dv IN6ADDR_ANY_INIT for an IPv6 address. .Pp If the .Dv AI_PASSIVE bit is not set, the returned socket address structure will be ready for use in a call to .Xr connect 2 for a connection-oriented protocol or .Xr connect 2 , .Xr sendto 2 , or .Xr sendmsg 2 if a connectionless protocol was chosen. The .Tn IP address portion of the socket address structure will be set to the loopback address if .Fa hostname is the null pointer and .Dv AI_PASSIVE is not set. .El .El .Pp All other elements of the .Li addrinfo structure passed via .Fa hints must be zero or the null pointer. .Pp If .Fa hints is the null pointer, .Fn getaddrinfo behaves as if the caller provided a .Li struct addrinfo with .Fa ai_family set to .Dv PF_UNSPEC and all other elements set to zero or .Dv NULL . .Pp After a successful call to .Fn getaddrinfo , .Fa *res is a pointer to a linked list of one or more .Li addrinfo structures. The list can be traversed by following the .Fa ai_next pointer in each .Li addrinfo structure until a null pointer is encountered. The three members -.Fa ai_family, -.Fa ai_socktype, +.Fa ai_family , +.Fa ai_socktype , and .Fa ai_protocol in each returned .Li addrinfo structure are suitable for a call to .Xr socket 2 . For each .Li addrinfo structure in the list, the .Fa ai_addr member points to a filled-in socket address structure of length .Fa ai_addrlen . .Pp This implementation of .Fn getaddrinfo allows numeric IPv6 address notation with scope identifier, as documented in chapter 11 of RFC 4007. By appending the percent character and scope identifier to addresses, one can fill the .Li sin6_scope_id field for addresses. This would make management of scoped addresses easier and allows cut-and-paste input of scoped addresses. .Pp At this moment the code supports only link-local addresses with the format. The scope identifier is hardcoded to the name of the hardware interface associated with the link .Po such as .Li ne0 .Pc . An example is .Dq Li fe80::1%ne0 , which means .Do .Li fe80::1 on the link associated with the .Li ne0 interface .Dc . .Pp The current implementation assumes a one-to-one relationship between the interface and link, which is not necessarily true from the specification. .Pp All of the information returned by .Fn getaddrinfo is dynamically allocated: the .Li addrinfo structures themselves as well as the socket address structures and the canonical host name strings included in the .Li addrinfo structures. .Pp Memory allocated for the dynamically allocated structures created by a successful call to .Fn getaddrinfo is released by the .Fn freeaddrinfo function. The .Fa ai pointer should be a .Li addrinfo structure created by a call to .Fn getaddrinfo . .Sh RETURN VALUES .Fn getaddrinfo returns zero on success or one of the error codes listed in .Xr gai_strerror 3 if an error occurs. .Sh EXAMPLES The following code tries to connect to .Dq Li www.kame.net service .Dq Li http via a stream socket. It loops through all the addresses available, regardless of address family. If the destination resolves to an IPv4 address, it will use an .Dv AF_INET socket. Similarly, if it resolves to IPv6, an .Dv AF_INET6 socket is used. Observe that there is no hardcoded reference to a particular address family. The code works even if .Fn getaddrinfo returns addresses that are not IPv4/v6. .Bd -literal -offset indent struct addrinfo hints, *res, *res0; int error; int s; const char *cause = NULL; memset(&hints, 0, sizeof(hints)); hints.ai_family = PF_UNSPEC; hints.ai_socktype = SOCK_STREAM; error = getaddrinfo("www.kame.net", "http", &hints, &res0); if (error) { errx(1, "%s", gai_strerror(error)); /* NOTREACHED */ } s = -1; for (res = res0; res; res = res->ai_next) { s = socket(res->ai_family, res->ai_socktype, res->ai_protocol); if (s < 0) { cause = "socket"; continue; } if (connect(s, res->ai_addr, res->ai_addrlen) < 0) { cause = "connect"; close(s); s = -1; continue; } break; /* okay we got one */ } if (s < 0) { err(1, "%s", cause); /* NOTREACHED */ } freeaddrinfo(res0); .Ed .Pp The following example tries to open a wildcard listening socket onto service .Dq Li http , for all the address families available. .Bd -literal -offset indent struct addrinfo hints, *res, *res0; int error; int s[MAXSOCK]; int nsock; const char *cause = NULL; memset(&hints, 0, sizeof(hints)); hints.ai_family = PF_UNSPEC; hints.ai_socktype = SOCK_STREAM; hints.ai_flags = AI_PASSIVE; error = getaddrinfo(NULL, "http", &hints, &res0); if (error) { errx(1, "%s", gai_strerror(error)); /* NOTREACHED */ } nsock = 0; for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { s[nsock] = socket(res->ai_family, res->ai_socktype, res->ai_protocol); if (s[nsock] < 0) { cause = "socket"; continue; } if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) { cause = "bind"; close(s[nsock]); continue; } (void) listen(s[nsock], 5); nsock++; } if (nsock == 0) { err(1, "%s", cause); /* NOTREACHED */ } freeaddrinfo(res0); .Ed .Sh SEE ALSO .Xr bind 2 , .Xr connect 2 , .Xr send 2 , .Xr socket 2 , .Xr gai_strerror 3 , .Xr gethostbyname 3 , .Xr getnameinfo 3 , .Xr getservbyname 3 , .Xr resolver 3 , .Xr hosts 5 , .Xr resolv.conf 5 , .Xr services 5 , .Xr hostname 7 , .Xr named 8 .Rs .%A R. Gilligan .%A S. Thomson .%A J. Bound .%A J. McCann .%A W. Stevens .%T Basic Socket Interface Extensions for IPv6 .%R RFC 3493 .%D February 2003 .Re .Rs .%A S. Deering .%A B. Haberman .%A T. Jinmei .%A E. Nordmark .%A B. Zill .%T "IPv6 Scoped Address Architecture" .%R RFC 4007 .%D March 2005 .Re .Rs .%A Craig Metz .%T Protocol Independence Using the Sockets API .%B "Proceedings of the freenix track: 2000 USENIX annual technical conference" .%D June 2000 .Re .Sh STANDARDS The .Fn getaddrinfo function is defined by the .St -p1003.1-2004 specification and documented in .Dv "RFC 3493" , .Dq Basic Socket Interface Extensions for IPv6 . Index: head/lib/libc/net/sctp_recvmsg.3 =================================================================== --- head/lib/libc/net/sctp_recvmsg.3 (revision 276005) +++ head/lib/libc/net/sctp_recvmsg.3 (revision 276006) @@ -1,294 +1,294 @@ .\" Copyright (c) 1983, 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. .\" .\" $FreeBSD$ .\" .Dd August 13, 2007 .Dt SCTP_RECVMSG 3 .Os .Sh NAME .Nm sctp_recvmsg .Nd receive a message from an SCTP socket .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/sctp.h .Ft ssize_t .Fo sctp_recvmsg .Fa "int s" "void *msg" "size_t len" "struct sockaddr * restrict from" .Fa "socklen_t * restrict fromlen" "struct sctp_sndrcvinfo *sinfo" "int *flags" .Fc .Sh DESCRIPTION The .Fn sctp_recvmsg system call is used to receive a message from another SCTP endpoint. The .Fn sctp_recvmsg call is used by one-to-one (SOCK_STREAM) type sockets after a successful .Fn connect call or after the application has performed a .Fn listen followed by a successful .Fn accept . For a one-to-many (SOCK_SEQPACKET) type socket, an endpoint may call .Fn sctp_recvmsg after having implicitly started an association via one of the send calls including .Fn sctp_sendmsg , .Fn sendto and .Fn sendmsg . Or, an application may also receive a message after having called .Fn listen with a positive backlog to enable the reception of new associations. .Pp The address of the sender is held in the .Fa from argument with .Fa fromlen specifying its size. At the completion of a successful .Fn sctp_recvmsg call .Fa from will hold the address of the peer and .Fa fromlen will hold the length of that address. Note that the address is bounded by the initial value of .Fa fromlen which is used as an in/out variable. .Pp The length of the message .Fa msg to be received is bounded by .Fa len . If the message is too long to fit in the users receive buffer, then the .Fa flags argument will .Em not have the .Dv MSG_EOF flag applied. If the message is a complete message then the .Fa flags argument will have .Dv MSG_EOF set. Locally detected errors are indicated by a return value of -1 with .Va errno set accordingly. The .Fa flags argument may also hold the value .Dv MSG_NOTIFICATION . When this occurs it indicates that the message received is .Em not from the peer endpoint, but instead is a notification from the SCTP stack (see .Xr sctp 4 for more details). Note that no notifications are ever given unless the user subscribes to such notifications using the .Dv SCTP_EVENTS socket option. .Pp If no messages are available at the socket then .Fn sctp_recvmsg normally blocks on the reception of a message or NOTIFICATION, unless the socket has been placed in non-blocking I/O mode. The .Xr select 2 system call may be used to determine when it is possible to receive a message. .Pp The .Fa sinfo argument is defined as follows. .Bd -literal struct sctp_sndrcvinfo { uint16_t sinfo_stream; /* Stream arriving on */ uint16_t sinfo_ssn; /* Stream Sequence Number */ uint16_t sinfo_flags; /* Flags on the incoming message */ uint32_t sinfo_ppid; /* The ppid field */ uint32_t sinfo_context; /* context field */ uint32_t sinfo_timetolive; /* not used by sctp_recvmsg */ uint32_t sinfo_tsn; /* The transport sequence number */ uint32_t sinfo_cumtsn; /* The cumulative acknowledgment point */ sctp_assoc_t sinfo_assoc_id; /* The association id of the peer */ }; .Ed .Pp The .Fa sinfo->sinfo_ppid field is an opaque 32 bit value that is passed transparently through the stack from the peer endpoint. Note that the stack passes this value without regard to byte order. .Pp The .Fa sinfo->sinfo_flags field may include the following: .Bd -literal #define SCTP_UNORDERED 0x0400 /* Message is un-ordered */ .Ed .Pp The .Dv SCTP_UNORDERED flag is used to specify that the message arrived with no specific order and was delivered to the peer application as soon as possible. When this flag is absent the message was delivered in order within the stream it was received. .Pp The .Fa sinfo->sinfo_stream field is the SCTP stream that the message was received on. Streams in SCTP are reliable (or partially reliable) flows of ordered messages. .Pp The .Fa sinfo->sinfo_context field is used only if the local application set an association level context with the .Dv SCTP_CONTEXT socket option. Optionally a user process can use this value to index some application specific data structure for all data coming from a specific association. .Pp The .Fa sinfo->sinfo_ssn field will hold the stream sequence number assigned by the peer endpoint if the message is .Em not unordered. For unordered messages this field holds an undefined value. .Pp The .Fa sinfo->sinfo_tsn field holds a transport sequence number (TSN) that was assigned to this message by the peer endpoint. For messages that fit in or less than the path MTU this will be the only TSN assigned. Note that for messages that span multiple TSNs this value will be one of the TSNs that was used on the message. .Pp The .Fa sinfo->sinfo_cumtsn field holds the current cumulative acknowledgment point of the transport association. Note that this may be larger or smaller than the TSN assigned to the message itself. .Pp The .Fa sinfo->sinfo_assoc_id is the unique association identification that was assigned to the association. For one-to-many (SOCK_SEQPACKET) type sockets this value can be used to send data to the peer without the use of an address field. It is also quite useful in setting various socket options on the specific association (see .Xr sctp 4 ) . .Pp The .Fa sinfo->info_timetolive field is not used by .Fn sctp_recvmsg . .Sh RETURN VALUES The call returns the number of bytes received, or -1 if an error occurred. .Sh ERRORS The .Fn sctp_recvmsg system call fails if: .Bl -tag -width Er .It Bq Er EBADF An invalid descriptor was specified. .It Bq Er ENOTSOCK The argument .Fa s is not a socket. .It Bq Er EFAULT An invalid user space address was specified for an argument. .It Bq Er EMSGSIZE The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. .It Bq Er EAGAIN The socket is marked non-blocking and the requested operation would block. .It Bq Er ENOBUFS The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. .It Bq Er ENOBUFS The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. .It Bq Er EHOSTUNREACH The remote host was unreachable. .It Bq Er ENOTCONN On a one-to-one style socket no association exists. .It Bq Er ECONNRESET An abort was received by the stack while the user was attempting to send data to the peer. .It Bq Er ENOENT On a one to many style socket no address is specified so that the association cannot be located or the SCTP_ABORT flag was specified on a non-existing association. .It Bq Er EPIPE The socket is unable to send anymore data .Dv ( SBS_CANTSENDMORE has been set on the socket). This typically means that the socket is not connected and is a one-to-one style socket. .El .Sh SEE ALSO +.Xr getsockopt 2 , .Xr recv 2 , .Xr select 2 , +.Xr setsockopt 2 , .Xr socket 2 , .Xr write 2 , -.Xr getsockopt 2 , -.Xr setsockopt 2 , .Xr sctp_send 3 , .Xr sctp_sendmsg 3 , .Xr sendmsg 3 , .Xr sctp 4 Index: head/lib/libc/net/sctp_send.3 =================================================================== --- head/lib/libc/net/sctp_send.3 (revision 276005) +++ head/lib/libc/net/sctp_send.3 (revision 276006) @@ -1,350 +1,350 @@ .\" Copyright (c) 1983, 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. .\" .\" $FreeBSD$ .\" .Dd December 15, 2006 .Dt SCTP_SEND 3 .Os .Sh NAME .Nm sctp_send , .Nm sctp_sendx .Nd send a message from an SCTP socket .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .In netinet/sctp.h .Ft ssize_t .Fo sctp_send .Fa "int sd" "const void *msg" "size_t len" .Fa "const struct sctp_sndrcvinfo *sinfo" "int flags" .Fc .Ft ssize_t .Fo sctp_sendx .Fa "int sd" "const void *msg" "size_t len" "struct sockaddr *addrs" .Fa "int addrcnt" "const struct sctp_sndrcvinfo *sinfo" "int flags" .Fc .Sh DESCRIPTION The .Fn sctp_send system call is used to transmit a message to another SCTP endpoint. .Fn sctp_send may be used to send data to an existing association for both one-to-many (SOCK_SEQPACKET) and one-to-one (SOCK_STREAM) socket types. The length of the message .Fa msg is given by .Fa len . If the message is too long to pass atomically through the underlying protocol, .Va errno is set to .Er EMSGSIZE , -1 is returned, and the message is not transmitted. .Pp No indication of failure to deliver is implicit in a .Fn sctp_send . Locally detected errors are indicated by a return value of -1. .Pp If no space is available at the socket to hold the message to be transmitted, then .Fn sctp_send normally blocks, unless the socket has been placed in non-blocking I/O mode. The .Xr select 2 system call may be used to determine when it is possible to send more data on one-to-one type (SOCK_STREAM) sockets. .Pp The .Fa sinfo structure is used to control various SCTP features and has the following format: .Bd -literal struct sctp_sndrcvinfo { uint16_t sinfo_stream; /* Stream sending to */ uint16_t sinfo_ssn; /* valid for recv only */ uint16_t sinfo_flags; /* flags to control sending */ uint32_t sinfo_ppid; /* ppid field */ uint32_t sinfo_context; /* context field */ uint32_t sinfo_timetolive; /* timetolive for PR-SCTP */ uint32_t sinfo_tsn; /* valid for recv only */ uint32_t sinfo_cumtsn; /* valid for recv only */ sctp_assoc_t sinfo_assoc_id; /* The association id */ }; .Ed .Pp The .Fa sinfo->sinfo_ppid argument is an opaque 32 bit value that is passed transparently through the stack to the peer endpoint. It will be available on reception of a message (see .Xr sctp_recvmsg 3 ) . Note that the stack passes this value without regard to byte order. .Pp The .Fa sinfo->sinfo_flags argument may include one or more of the following: .Bd -literal #define SCTP_EOF 0x0100 /* Start a shutdown procedures */ #define SCTP_ABORT 0x0200 /* Send an ABORT to peer */ #define SCTP_UNORDERED 0x0400 /* Message is un-ordered */ #define SCTP_ADDR_OVER 0x0800 /* Override the primary-address */ #define SCTP_SENDALL 0x1000 /* Send this on all associations */ /* for the endpoint */ /* The lower byte is an enumeration of PR-SCTP policies */ #define SCTP_PR_SCTP_TTL 0x0001 /* Time based PR-SCTP */ #define SCTP_PR_SCTP_BUF 0x0002 /* Buffer based PR-SCTP */ #define SCTP_PR_SCTP_RTX 0x0003 /* Number of retransmissions based PR-SCTP */ .Ed .Pp The flag .Dv SCTP_EOF is used to instruct the SCTP stack to queue this message and then start a graceful shutdown of the association. All remaining data in queue will be sent after which the association will be shut down. .Pp .Dv SCTP_ABORT is used to immediately terminate an association. An abort is sent to the peer and the local TCB is destroyed. .Pp .Dv SCTP_UNORDERED is used to specify that the message being sent has no specific order and should be delivered to the peer application as soon as possible. When this flag is absent messages are delivered in order within the stream they are sent, but without respect to order to peer streams. .Pp The flag .Dv SCTP_ADDR_OVER is used to specify that a specific address should be used. Normally SCTP will use only one of a multi-homed peers addresses as the primary address to send to. By default, no matter what the .Fa to argument is, this primary address is used to send data. By specifying this flag, the user is asking the stack to ignore the primary address and instead use the specified address not only as a lookup mechanism to find the association but also as the actual address to send to. .Pp For a one-to-many type (SOCK_SEQPACKET) socket the flag .Dv SCTP_SENDALL can be used as a convenient way to make one send call and have all associations that are under the socket get a copy of the message. Note that this mechanism is quite efficient and makes only one actual copy of the data which is shared by all the associations for sending. .Pp The remaining flags are used for the partial reliability extension (RFC3758) and will only be effective if the peer endpoint supports this extension. This option specifies what local policy the local endpoint should use in skipping data. If none of these options are set, then data is never skipped over. .Pp .Dv SCTP_PR_SCTP_TTL is used to indicate that a time based lifetime is being applied to the data. The .Fa sinfo->sinfo_timetolive argument is then a number of milliseconds for which the data is attempted to be transmitted. If that many milliseconds elapse and the peer has not acknowledged the data, the data will be skipped and no longer transmitted. Note that this policy does not even assure that the data will ever be sent. In times of a congestion with large amounts of data being queued, the .Fa sinfo->sinfo_timetolive may expire before the first transmission is ever made. .Pp The .Dv SCTP_PR_SCTP_BUF based policy transforms the .Fa sinfo->sinfo_timetolive field into a total number of bytes allowed on the outbound send queue. If that number or more bytes are in queue, then other buffer-based sends are looked to be removed and skipped. Note that this policy may also result in the data never being sent if no buffer based sends are in queue and the maximum specified by .Fa timetolive bytes is in queue. .Pp The .Dv SCTP_PR_SCTP_RTX policy transforms the .Fa sinfo->sinfo_timetolive into a number of retransmissions to allow. This policy always assures that at a minimum one send attempt is made of the data. After which no more than .Fa sinfo->sinfo_timetolive retransmissions will be made before the data is skipped. .Pp .Fa sinfo->sinfo_stream is the SCTP stream that you wish to send the message on. Streams in SCTP are reliable (or partially reliable) flows of ordered messages. .Pp The .Fa sinfo->sinfo_assoc_id field is used to select the association to send to on a one-to-many socket. For a one-to-one socket, this field is ignored. .Pp The .Fa sinfo->sinfo_context field is used only in the event the message cannot be sent. This is an opaque value that the stack retains and will give to the user when a failed send is given if that notification is enabled (see .Xr sctp 4 ) . Normally a user process can use this value to index some application specific data structure when a send cannot be fulfilled. .Pp The .Fa flags argument holds the same meaning and values as those found in .Xr sendmsg 2 but is generally ignored by SCTP. .Pp The fields .Fa sinfo->sinfo_ssn , .Fa sinfo->sinfo_tsn , and .Fa sinfo->sinfo_cumtsn are used only when receiving messages and are thus ignored by .Fn sctp_send . The function .Fn sctp_sendx has the same properties as .Fn sctp_send with the additional arguments of an array of sockaddr structures passed in. With the .Fa addrs argument being given as an array of addresses to be sent to and the .Fa addrcnt argument indicating how many socket addresses are in the passed in array. Note that all of the addresses will only be used when an implicit association is being set up. This allows the user the equivalent behavior as doing a .Fn sctp_connectx followed by a .Fn sctp_send to the association. Note that if the .Fa sinfo->sinfo_assoc_id field is 0, then the first address will be used to look up the association in place of the association id. If both an address and an association id are specified, the association id has priority. .Sh RETURN VALUES The call returns the number of characters sent, or -1 if an error occurred. .Sh ERRORS The .Fn sctp_send system call fails if: .Bl -tag -width Er .It Bq Er EBADF An invalid descriptor was specified. .It Bq Er ENOTSOCK The argument .Fa s is not a socket. .It Bq Er EFAULT An invalid user space address was specified for an argument. .It Bq Er EMSGSIZE The socket requires that message be sent atomically, and the size of the message to be sent made this impossible. .It Bq Er EAGAIN The socket is marked non-blocking and the requested operation would block. .It Bq Er ENOBUFS The system was unable to allocate an internal buffer. The operation may succeed when buffers become available. .It Bq Er ENOBUFS The output queue for a network interface was full. This generally indicates that the interface has stopped sending, but may be caused by transient congestion. .It Bq Er EHOSTUNREACH The remote host was unreachable. .It Bq Er ENOTCONN On a one-to-one style socket no association exists. .It Bq Er ECONNRESET An abort was received by the stack while the user was attempting to send data to the peer. .It Bq Er ENOENT On a one-to-many style socket no address is specified so that the association cannot be located or the SCTP_ABORT flag was specified on a non-existing association. .It Bq Er EPIPE The socket is unable to send anymore data .Dv ( SBS_CANTSENDMORE has been set on the socket). This typically means that the socket is not connected and is a one-to-one style socket. .El .Sh SEE ALSO .Xr getsockopt 2 , .Xr recv 2 , .Xr select 2 , .Xr sendmsg 2 , .Xr socket 2 , -.Xr write 2 +.Xr write 2 , .Xr sctp_connectx 3 , .Xr sctp_recvmsg 3 , .Xr sctp_sendmsg 3 , .Xr sctp 4 .Sh BUGS Because .Fn sctp_send may have multiple associations under one endpoint, a select on write will only work for a one-to-one style socket. Index: head/lib/libc/posix1e/acl_set_flagset_np.3 =================================================================== --- head/lib/libc/posix1e/acl_set_flagset_np.3 (revision 276005) +++ head/lib/libc/posix1e/acl_set_flagset_np.3 (revision 276006) @@ -1,85 +1,85 @@ .\"- .\" Copyright (c) 2008, 2009 Edward Tomasz Napierala .\" 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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. .\" .\" $FreeBSD$ .\" .Dd October 30, 2014 .Dt ACL_SET_FLAGSET_NP 3 .Os .Sh NAME .Nm acl_set_flagset_np .Nd set the flags of an NFSv4 ACL entry .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/acl.h .Ft int .Fn acl_set_flagset_np "acl_entry_t entry_d" "acl_flagset_t flagset_d" .Sh DESCRIPTION The .Fn acl_set_flagset_np function is a non-portable call that sets the flags of NFSv4 ACL entry .Fa entry_d with the flags contained in .Fa flagset_d . .Pp This call brands the ACL as NFSv4. .Sh RETURN VALUES .Rv -std acl_set_flagset_np .Sh ERRORS The .Fn acl_set_flagset_np function fails if: .Bl -tag -width Er .It Bq Er EINVAL Argument .Fa entry_d is not a valid descriptor for an ACL entry. ACL is already branded as POSIX.1e. .El .Sh SEE ALSO .Xr acl 3 , .Xr acl_add_flag_np 3 , -.Xr acl_get_brand_np 3 , .Xr acl_clear_flags_np 3 , .Xr acl_delete_flag_np 3 , +.Xr acl_get_brand_np 3 , .Xr acl_get_flagset_np 3 , .Xr posix1e 3 .Sh STANDARDS POSIX.1e is described in IEEE POSIX.1e draft 17. .Sh HISTORY POSIX.1e support was introduced in .Fx 4.0 . The .Fn acl_set_flagset_np function was added in .Fx 8.0 . .Sh AUTHORS The .Fn acl_set_flagset_np function was written by .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org . Index: head/lib/libc/stdlib/atexit.3 =================================================================== --- head/lib/libc/stdlib/atexit.3 (revision 276005) +++ head/lib/libc/stdlib/atexit.3 (revision 276006) @@ -1,103 +1,103 @@ .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Chris Torek and the American National Standards Committee X3, .\" on Information Processing Systems. .\" .\" 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. .\" .\" @(#)atexit.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd September 6, 2002 .Dt ATEXIT 3 .Os .Sh NAME .Nm atexit .Nd register a function to be called on exit .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In stdlib.h .Ft int .Fn atexit "void (*function)(void)" .Ft int .Fn atexit_b "void (^function)(void)" .Sh DESCRIPTION The .Fn atexit function registers the given .Fa function to be called at program exit, whether via .Xr exit 3 or via return from the program's .Fn main . Functions so registered are called in reverse order; no arguments are passed. .Pp These functions must not call .Fn exit ; if it should be necessary to terminate the process while in such a function, the .Xr _exit 2 function should be used. (Alternatively, the function may cause abnormal process termination, for example by calling .Xr abort 3 . ) .Pp At least 32 functions can always be registered, and more are allowed as long as sufficient memory can be allocated. .Pp The .Fn atexit_b function behaves identically to .Fn atexit , except that it takes a block, rather than a function pointer. .\" XXX {ATEXIT_MAX} is not implemented yet .Sh RETURN VALUES .Rv -std atexit .Sh ERRORS .Bl -tag -width Er .It Bq Er ENOMEM No memory was available to add the function to the list. The existing list of functions is unmodified. .It Bq Er ENOSYS The .Fn atexit_b -function was called by a program that did not supply a +function was called by a program that did not supply a .Fn _Block_copy implementation. .El .Sh SEE ALSO -.Xr at_quick_exit 3 +.Xr at_quick_exit 3 , .Xr exit 3 .Sh STANDARDS The .Fn atexit function conforms to .St -isoC . Index: head/lib/libc/stdlib/exit.3 =================================================================== --- head/lib/libc/stdlib/exit.3 (revision 276005) +++ head/lib/libc/stdlib/exit.3 (revision 276006) @@ -1,132 +1,132 @@ .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" the American National Standards Committee X3, on Information .\" Processing Systems. .\" .\" 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. .\" .\" @(#)exit.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd September 9, 2002 .Dt EXIT 3 .Os .Sh NAME .Nm exit , _Exit .Nd perform normal program termination .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In stdlib.h .Ft void .Fn exit "int status" .Ft void .Fn _Exit "int status" .Sh DESCRIPTION The .Fn exit and .Fn _Exit functions terminate a process. .Pp Before termination, .Fn exit performs the following functions in the order listed: .Bl -enum -offset indent .It Call the functions registered with the .Xr atexit 3 function, in the reverse order of their registration. .It Flush all open output streams. .It Close all open streams. .It Unlink all files created with the .Xr tmpfile 3 function. .El .Pp The .Fn _Exit function terminates without calling the functions registered with the .Xr atexit 3 function, and may or may not perform the other actions listed. Both functions make the low-order eight bits of the .Fa status argument available to a parent process which has called a .Xr wait 2 Ns -family function. .Pp The C Standard .Pq St -isoC-99 defines the values .Li 0 , .Dv EXIT_SUCCESS , and .Dv EXIT_FAILURE as possible values of .Fa status . Cooperating processes may use other values; in a program which might be called by a mail transfer agent, the values described in .Xr sysexits 3 may be used to provide more information to the parent process. .Pp Note that .Fn exit does nothing to prevent bottomless recursion should a function registered using .Xr atexit 3 itself call .Fn exit . Such functions must call .Fn _Exit instead (although this has other effects as well which may not be desired). .Sh RETURN VALUES The .Fn exit and .Fn _Exit functions never return. .Sh SEE ALSO .Xr _exit 2 , .Xr wait 2 , -.Xr atexit 3 , .Xr at_quick_exit 3 , +.Xr atexit 3 , .Xr intro 3 , .Xr quick_exit 3 , .Xr sysexits 3 , .Xr tmpfile 3 .Sh STANDARDS The .Fn exit and .Fn _Exit functions conform to .St -isoC-99 . Index: head/lib/libc/string/strspn.3 =================================================================== --- head/lib/libc/string/strspn.3 (revision 276005) +++ head/lib/libc/string/strspn.3 (revision 276006) @@ -1,111 +1,111 @@ .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Chris Torek and the American National Standards Committee X3, .\" on Information Processing Systems. .\" .\" 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. .\" .\" @(#)strspn.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd May 24, 2014 .Dt STRSPN 3 .Os .Sh NAME .Nm strspn , .Nm strcspn .Nd span a string .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In string.h .Ft size_t .Fn strspn "const char *s" "const char *charset" .Ft size_t .Fn strcspn "const char *s" "const char *charset" .Sh DESCRIPTION The .Fn strspn function spans the initial part of the null-terminated string .Fa s as long as the characters from .Fa s occur in the null-terminated string .Fa charset . In other words, it computes the string array index of the first character of .Fa s which is not in .Fa charset , else the index of the first null character. .Pp The .Fn strcspn function spans the initial part of the null-terminated string .Fa s as long as the characters from .Fa s -.Sy do not +.Sy do not occur in the null-terminated string .Fa charset .Po it spans the .Sy complement of .Fa charset .Pc . In other words, it computes the string array index of the first character of .Fa s which is also in .Fa charset , else the index of the first null character. .Sh RETURN VALUES The .Fn strspn and .Fn strcspn functions return the number of characters spanned. .Sh SEE ALSO .Xr memchr 3 , .Xr strchr 3 , .Xr strpbrk 3 , .Xr strrchr 3 , .Xr strsep 3 , .Xr strstr 3 , .Xr strtok 3 , .Xr wcsspn 3 .Sh STANDARDS The .Fn strspn and .Fn strcspn functions conform to .St -isoC . Index: head/lib/libc/sys/access.2 =================================================================== --- head/lib/libc/sys/access.2 (revision 276005) +++ head/lib/libc/sys/access.2 (revision 276006) @@ -1,243 +1,243 @@ .\" Copyright (c) 1980, 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. .\" 4. 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. .\" .\" @(#)access.2 8.2 (Berkeley) 4/1/94 .\" $FreeBSD$ .\" .Dd September 15, 2014 .Dt ACCESS 2 .Os .Sh NAME .Nm access , .Nm eaccess , .Nm faccessat .Nd check accessibility of a file .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft int .Fn access "const char *path" "int mode" .Ft int .Fn eaccess "const char *path" "int mode" .Ft int .Fn faccessat "int fd" "const char *path" "int mode" "int flag" .Sh DESCRIPTION The .Fn access and .Fn eaccess system calls check the accessibility of the file named by the .Fa path argument for the access permissions indicated by the .Fa mode argument. The value of .Fa mode is either the bitwise-inclusive OR of the access permissions to be checked .Dv ( R_OK for read permission, .Dv W_OK for write permission, and .Dv X_OK for execute/search permission), or the existence test .Pq Dv F_OK . .Pp For additional information, see the .Sx "File Access Permission" section of .Xr intro 2 . .Pp The .Fn eaccess system call uses the effective user ID and the group access list to authorize the request; the .Fn access system call uses the real user ID in place of the effective user ID, the real group ID in place of the effective group ID, and the rest of the group access list. .Pp The .Fn faccessat system call is equivalent to .Fn access except in the case where .Fa path specifies a relative path. In this case the file whose accessibility is to be determined is located relative to the directory associated with the file descriptor .Fa fd instead of the current working directory. If .Fn faccessat is passed the special value .Dv AT_FDCWD in the .Fa fd parameter, the current working directory is used and the behavior is identical to a call to .Fn access . Values for .Fa flag are constructed by a bitwise-inclusive OR of flags from the following list, defined in .In fcntl.h : .Bl -tag -width indent .It Dv AT_EACCESS The checks for accessibility are performed using the effective user and group IDs instead of the real user and group ID as required in a call to .Fn access . .El .Pp Even if a process's real or effective user has appropriate privileges and indicates success for .Dv X_OK , the file may not actually have execute permission bits set. Likewise for .Dv R_OK and .Dv W_OK . .Sh RETURN VALUES .Rv -std .Sh ERRORS .Fn access , .Fn eaccess , or -.Fn faccessat +.Fn faccessat will fail if: .Bl -tag -width Er .It Bq Er EINVAL The value of the .Fa mode argument is invalid. .It Bq Er ENOTDIR A component of the path prefix is not a directory. .It Bq Er ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. .It Bq Er ENOENT The named file does not exist. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .It Bq Er EROFS Write access is requested for a file on a read-only file system. .It Bq Er ETXTBSY Write access is requested for a pure procedure (shared text) file presently being executed. .It Bq Er EACCES Permission bits of the file mode do not permit the requested access, or search permission is denied on a component of the path prefix. .It Bq Er EFAULT The .Fa path argument points outside the process's allocated address space. .It Bq Er EIO An I/O error occurred while reading from or writing to the file system. .El .Pp Also, the .Fn faccessat system call may fail if: .Bl -tag -width Er .It Bq Er EBADF The .Fa path argument does not specify an absolute path and the .Fa fd argument is neither .Dv AT_FDCWD nor a valid file descriptor. .It Bq Er EINVAL The value of the .Fa flag argument is not valid. .It Bq Er ENOTDIR The .Fa path argument is not an absolute path and .Fa fd is neither .Dv AT_FDCWD nor a file descriptor associated with a directory. .El .Sh SEE ALSO .Xr chmod 2 , .Xr intro 2 , .Xr stat 2 .Sh STANDARDS The .Fn access system call is expected to conform to .St -p1003.1-90 . The .Fn faccessat system call follows The Open Group Extended API Set 2 specification. .Sh HISTORY The .Fn access function appeared in .At v7 . The .Fn faccessat system call appeared in .Fx 8.0 . .Sh SECURITY CONSIDERATIONS The .Fn access system call is a potential security hole due to race conditions and should never be used. Set-user-ID and set-group-ID applications should restore the effective user or group ID, and perform actions directly rather than use .Fn access to simulate access checks for the real user or group ID. The .Fn eaccess system call likewise may be subject to races if used inappropriately. .Pp .Fn access remains useful for providing clues to users as to whether operations make sense for particular filesystem objects (e.g. 'delete' menu item only highlighted in a writable folder ... avoiding interpretation of the st_mode bits that the application might not understand -- e.g. in the case of AFS). It also allows a cheaper file existence test than .Xr stat 2 . Index: head/lib/libc/sys/getdirentries.2 =================================================================== --- head/lib/libc/sys/getdirentries.2 (revision 276005) +++ head/lib/libc/sys/getdirentries.2 (revision 276006) @@ -1,185 +1,186 @@ .\" Copyright (c) 1989, 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. .\" 4. 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. .\" .\" @(#)getdirentries.2 8.2 (Berkeley) 5/3/95 .\" $FreeBSD$ .\" .Dd May 3, 1995 .Dt GETDIRENTRIES 2 .Os .Sh NAME .Nm getdirentries , .Nm getdents .Nd "get directory entries in a file system independent format" .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In dirent.h .Ft int .Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep" .Ft int .Fn getdents "int fd" "char *buf" "int nbytes" .Sh DESCRIPTION The .Fn getdirentries and .Fn getdents system calls read directory entries from the directory referenced by the file descriptor .Fa fd into the buffer pointed to by .Fa buf , in a file system independent format. Up to .Fa nbytes of data will be transferred. The .Fa nbytes argument must be greater than or equal to the block size associated with the file, see .Xr stat 2 . Some file systems may not support these system calls with buffers smaller than this size. .Pp The data in the buffer is a series of .Vt dirent structures each containing the following entries: .Bd -literal -offset indent uint32_t d_fileno; uint16_t d_reclen; uint8_t d_type; uint8_t d_namlen; char d_name[MAXNAMELEN + 1]; /* see below */ .Ed .Pp The .Fa d_fileno entry is a number which is unique for each distinct file in the file system. Files that are linked by hard links (see .Xr link 2 ) have the same .Fa d_fileno . The .Fa d_reclen entry is the length, in bytes, of the directory record. The .Fa d_type entry is the type of the file pointed to by the directory record. The file type values are defined in .Fa . The .Fa d_name entry contains a null terminated file name. The .Fa d_namlen entry specifies the length of the file name excluding the null byte. Thus the actual size of .Fa d_name may vary from 1 to .Dv MAXNAMELEN \&+ 1. .Pp Entries may be separated by extra space. The .Fa d_reclen entry may be used as an offset from the start of a .Fa dirent structure to the next structure, if any. .Pp The actual number of bytes transferred is returned. The current position pointer associated with .Fa fd is set to point to the next block of entries. The pointer may not advance by the number of bytes returned by .Fn getdirentries or .Fn getdents . A value of zero is returned when the end of the directory has been reached. .Pp The .Fn getdirentries system call writes the position of the block read into the location pointed to by .Fa basep . Alternatively, the current position pointer may be set and retrieved by .Xr lseek 2 . The current position pointer should only be set to a value returned by .Xr lseek 2 , a value returned in the location pointed to by .Fa basep -.Fn ( getdirentries -only) +.Po Fn getdirentries +only +.Pc or zero. .Sh RETURN VALUES If successful, the number of bytes actually transferred is returned. Otherwise, -1 is returned and the global variable .Va errno is set to indicate the error. .Sh ERRORS The .Fn getdirentries system call will fail if: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument is not a valid file descriptor open for reading. .It Bq Er EFAULT Either .Fa buf or .Fa basep point outside the allocated address space. .It Bq Er EINVAL The file referenced by .Fa fd is not a directory, or .Fa nbytes is too small for returning a directory entry or block of entries, or the current position pointer is invalid. .It Bq Er EIO An .Tn I/O error occurred while reading from or writing to the file system. .El .Sh SEE ALSO .Xr lseek 2 , .Xr open 2 .Sh HISTORY The .Fn getdirentries system call first appeared in .Bx 4.4 . The .Fn getdents system call first appeared in .Fx 3.0 . Index: head/lib/libc/sys/getrlimit.2 =================================================================== --- head/lib/libc/sys/getrlimit.2 (revision 276005) +++ head/lib/libc/sys/getrlimit.2 (revision 276006) @@ -1,205 +1,205 @@ .\" Copyright (c) 1980, 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. .\" 4. 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. .\" .\" @(#)getrlimit.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd August 20, 2008 .Dt GETRLIMIT 2 .Os .Sh NAME .Nm getrlimit , .Nm setrlimit .Nd control maximum system resource consumption .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/time.h .In sys/resource.h .Ft int .Fn getrlimit "int resource" "struct rlimit *rlp" .Ft int .Fn setrlimit "int resource" "const struct rlimit *rlp" .Sh DESCRIPTION Limits on the consumption of system resources by the current process and each process it creates may be obtained with the .Fn getrlimit system call, and set with the .Fn setrlimit system call. .Pp The .Fa resource argument is one of the following: .Bl -tag -width RLIMIT_FSIZEAA .It Dv RLIMIT_AS The maximum amount (in bytes) of virtual memory the process is allowed to map. .It Dv RLIMIT_CORE The largest size (in bytes) .Xr core 5 file that may be created. .It Dv RLIMIT_CPU The maximum amount of cpu time (in seconds) to be used by each process. .It Dv RLIMIT_DATA The maximum size (in bytes) of the data segment for a process; this defines how far a program may extend its break with the .Xr sbrk 2 function. .It Dv RLIMIT_FSIZE The largest size (in bytes) file that may be created. .It Dv RLIMIT_MEMLOCK The maximum size (in bytes) which a process may lock into memory using the .Xr mlock 2 system call. .It Dv RLIMIT_NOFILE The maximum number of open files for this process. .It Dv RLIMIT_NPROC The maximum number of simultaneous processes for this user id. .It Dv RLIMIT_RSS The maximum size (in bytes) to which a process's resident set size may grow. This imposes a limit on the amount of physical memory to be given to a process; if memory is tight, the system will prefer to take memory from processes that are exceeding their declared resident set size. .It Dv RLIMIT_SBSIZE The maximum size (in bytes) of socket buffer usage for this user. This limits the amount of network memory, and hence the amount of mbufs, that this user may hold at any time. .It Dv RLIMIT_STACK The maximum size (in bytes) of the stack segment for a process; this defines how far a program's stack segment may be extended. Stack extension is performed automatically by the system. .It Dv RLIMIT_SWAP The maximum size (in bytes) of the swap space that may be reserved or used by all of this user id's processes. This limit is enforced only if bit 1 of the .Va vm.overcommit sysctl is set. Please see .Xr tuning 7 for a complete description of this sysctl. .It Dv RLIMIT_NPTS The maximum number of pseudo-terminals created by this user id. .It Dv RLIMIT_KQUEUES The maximum number of kqueues created by this user id. .El .Pp A resource limit is specified as a soft limit and a hard limit. When a soft limit is exceeded a process may receive a signal (for example, if the cpu time or file size is exceeded), but it will be allowed to continue execution until it reaches the hard limit (or modifies its resource limit). The .Vt rlimit structure is used to specify the hard and soft limits on a resource, .Bd -literal -offset indent struct rlimit { rlim_t rlim_cur; /* current (soft) limit */ rlim_t rlim_max; /* maximum value for rlim_cur */ }; .Ed .Pp Only the super-user may raise the maximum limits. Other users may only alter .Fa rlim_cur within the range from 0 to .Fa rlim_max or (irreversibly) lower .Fa rlim_max . .Pp An .Dq infinite value for a limit is defined as .Dv RLIM_INFINITY . .Pp Because this information is stored in the per-process information, this system call must be executed directly by the shell if it is to affect all future processes created by the shell; .Ic limit is thus a built-in command to .Xr csh 1 . .Pp The system refuses to extend the data or stack space when the limits would be exceeded in the normal way: a .Xr brk 2 function fails if the data space limit is reached. When the stack limit is reached, the process receives a segmentation fault .Pq Dv SIGSEGV ; if this signal is not caught by a handler using the signal stack, this signal will kill the process. .Pp A file I/O operation that would create a file larger that the process' soft limit will cause the write to fail and a signal .Dv SIGXFSZ to be generated; this normally terminates the process, but may be caught. When the soft cpu time limit is exceeded, a signal .Dv SIGXCPU is sent to the offending process. .Sh RETURN VALUES .Rv -std .Sh ERRORS The .Fn getrlimit and .Fn setrlimit system calls will fail if: .Bl -tag -width Er .It Bq Er EFAULT The address specified for .Fa rlp is invalid. .It Bq Er EPERM The limit specified to .Fn setrlimit would have raised the maximum limit value, and the caller is not the super-user. .El .Sh SEE ALSO .Xr csh 1 , .Xr quota 1 , .Xr quotactl 2 , -.Xr sigaltstack 2 , .Xr sigaction 2 , +.Xr sigaltstack 2 , .Xr sysctl 3 , .Xr ulimit 3 .Sh HISTORY The .Fn getrlimit system call appeared in .Bx 4.2 . Index: head/lib/libc/sys/poll.2 =================================================================== --- head/lib/libc/sys/poll.2 (revision 276005) +++ head/lib/libc/sys/poll.2 (revision 276006) @@ -1,273 +1,273 @@ .\" $NetBSD: poll.2,v 1.3 1996/09/07 21:53:08 mycroft Exp $ .\" $FreeBSD$ .\" .\" Copyright (c) 1996 Charles M. Hannum. 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by Charles M. Hannum. .\" 4. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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 November 13, 2014 .Dt POLL 2 .Os .Sh NAME .Nm poll .Nd synchronous I/O multiplexing .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In poll.h .Ft int .Fn poll "struct pollfd fds[]" "nfds_t nfds" "int timeout" .Ft int .Fo ppoll .Fa "struct pollfd fds[]" .Fa "nfds_t nfds" .Fa "const struct timespec * restrict timeout" .Fa "const sigset_t * restrict newsigmask" .Fc .Sh DESCRIPTION The .Fn poll system call examines a set of file descriptors to see if some of them are ready for I/O. The .Fa fds argument is a pointer to an array of pollfd structures as defined in .In poll.h (shown below). The .Fa nfds argument determines the size of the .Fa fds array. .Bd -literal struct pollfd { int fd; /* file descriptor */ short events; /* events to look for */ short revents; /* events returned */ }; .Ed .Pp The fields of .Fa struct pollfd are as follows: .Bl -tag -width XXXrevents .It fd File descriptor to poll. If fd is equal to -1 then .Fa revents is cleared (set to zero), and that pollfd is not checked. .It events Events to poll for. (See below.) .It revents Events which may occur. (See below.) .El .Pp The event bitmasks in .Fa events and .Fa revents have the following bits: .Bl -tag -width XXXPOLLWRNORM .It POLLIN Data other than high priority data may be read without blocking. .It POLLRDNORM Normal data may be read without blocking. .It POLLRDBAND Data with a non-zero priority may be read without blocking. .It POLLPRI High priority data may be read without blocking. .It POLLOUT .It POLLWRNORM Normal data may be written without blocking. .It POLLWRBAND Data with a non-zero priority may be written without blocking. .It POLLERR An exceptional condition has occurred on the device or socket. This flag is always checked, even if not present in the .Fa events bitmask. .It POLLHUP The device or socket has been disconnected. This flag is always checked, even if not present in the .Fa events bitmask. Note that POLLHUP and POLLOUT should never be present in the .Fa revents bitmask at the same time. .It POLLNVAL The file descriptor is not open. This flag is always checked, even if not present in the .Fa events bitmask. .El .Pp If .Fa timeout is neither zero nor INFTIM (-1), it specifies a maximum interval to wait for any file descriptor to become ready, in milliseconds. If .Fa timeout is INFTIM (-1), the poll blocks indefinitely. If .Fa timeout is zero, then .Fn poll will return without blocking. .Pp The -.Fn ppoll -system call, unlike +.Fn ppoll +system call, unlike .Fn poll , is used to safely wait until either a set of file descriptors becomes ready or until a signal is caught. The .Fa fds and .Fa nfds arguments are identical to the analogous arguments of .Fn poll . The .Fa timeout argument in .Fn ppoll points to a .Vt "const struct timespec" which is defined in .In sys/timespec.h (shown below) rather than the .Vt "int timeout" used by .Fn poll . A null pointer may be passed to indicate that .Fn ppoll should wait indefinitely. -Finally, +Finally, .Fa newsigmask specifies a signal mask which is set while waiting for input. -When +When .Fn ppoll returns, the original signal mask is restored. .Bd -literal struct timespec { time_t tv_sec; /* seconds */ long tv_nsec; /* and nanoseconds */ }; .Ed .Sh RETURN VALUES The .Fn poll system call returns the number of descriptors that are ready for I/O, or -1 if an error occurred. If the time limit expires, .Fn poll returns 0. If .Fn poll returns with an error, including one due to an interrupted system call, the .Fa fds array will be unmodified. .Sh COMPATIBILITY This implementation differs from the historical one in that a given file descriptor may not cause .Fn poll to return with an error. In cases where this would have happened in the historical implementation (e.g.\& trying to poll a .Xr revoke 2 Ns ed descriptor), this implementation instead copies the .Fa events bitmask to the .Fa revents bitmask. Attempting to perform I/O on this descriptor will then return an error. This behaviour is believed to be more useful. .Sh ERRORS An error return from .Fn poll indicates: .Bl -tag -width Er .It Bq Er EFAULT The .Fa fds argument points outside the process's allocated address space. .It Bq Er EINTR A signal was delivered before the time limit expired and before any of the selected events occurred. .It Bq Er EINVAL The specified time limit is invalid. One of its components is negative or too large. .El .Sh SEE ALSO .Xr accept 2 , .Xr connect 2 , .Xr kqueue 2 , .Xr pselect 2 , .Xr read 2 , .Xr recv 2 , .Xr select 2 , .Xr send 2 , .Xr write 2 .Sh STANDARDS The -.Fn poll +.Fn poll function conforms to .St -p1003.1-2001 . The -.Fn ppoll +.Fn ppoll is not specified by POSIX. .Sh HISTORY The .Fn poll function appeared in .At V . This manual page and the core of the implementation was taken from .Nx . The .Fn ppoll -function first appeared in -.Fx 11.0 +function first appeared in +.Fx 11.0 .Sh BUGS The distinction between some of the fields in the .Fa events and .Fa revents bitmasks is really not useful without STREAMS. The fields are defined for compatibility with existing software. Index: head/lib/libc/sys/posix_openpt.2 =================================================================== --- head/lib/libc/sys/posix_openpt.2 (revision 276005) +++ head/lib/libc/sys/posix_openpt.2 (revision 276006) @@ -1,140 +1,140 @@ .\" Copyright (c) 2008 Ed Schouten .\" All rights reserved. .\" .\" Portions of this software were developed under sponsorship from Snow .\" B.V., the Netherlands. .\" .\" 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 AUTHOR 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 AUTHOR 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. .\" .\" 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. .\" .\" $FreeBSD$ .\" .Dd March 21, 2013 .Dt POSIX_OPENPT 2 .Os .Sh NAME .Nm posix_openpt .Nd "open a pseudo-terminal device" .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In stdlib.h .In fcntl.h .Ft int .Fn posix_openpt "int oflag" .Sh DESCRIPTION The .Fn posix_openpt function allocates a new pseudo-terminal and establishes a connection with its master device. A slave device shall be created in .Pa /dev/pts . After the pseudo-terminal has been allocated, the slave device should have the proper permissions before it can be used (see .Xr grantpt 3 ) . The name of the slave device can be determined by calling .Xr ptsname 3 . .Pp The file status flags and file access modes of the open file description shall be set according to the value of .Fa oflag . Values for .Fa oflag are constructed by a bitwise-inclusive OR of flags from the following list, defined in .In fcntl.h : .Bl -tag -width ".Dv O_CLOEXEC" .It Dv O_RDWR Open for reading and writing. .It Dv O_NOCTTY If set .Fn posix_openpt shall not cause the terminal device to become the controlling terminal for the process. .It Dv O_CLOEXEC Set the close-on-exec flag for the new file descriptor. .El .Pp The .Fn posix_openpt function shall fail when .Fa oflag contains other values. .Sh RETURN VALUES Upon successful completion, the .Fn posix_openpt function shall allocate a new pseudo-terminal device and return a non-negative integer representing a file descriptor, which is connected to its master device. Otherwise, -1 shall be returned and errno set to indicate the error. .Sh ERRORS The .Fn posix_openpt function shall fail if: .Bl -tag -width Er .It Bq Er ENFILE The system file table is full. .It Bq Er EINVAL The value of .Fa oflag is not valid. .It Bq Er EAGAIN Out of pseudo-terminal resources. .El .Sh SEE ALSO -.Xr pts 4 , .Xr ptsname 3 , +.Xr pts 4 , .Xr tty 4 .Sh STANDARDS The .Fn posix_openpt function conforms to .St -p1003.1-2001 . The ability to use .Dv O_CLOEXEC is an extension to the standard. .Sh HISTORY The .Fn posix_openpt function appeared in .Fx 5.0 . In .Fx 8.0 , this function was changed to a system call. .Sh NOTES The flag .Dv O_NOCTTY is included for compatibility; in .Fx , opening a terminal does not cause it to become a process's controlling terminal. .Sh AUTHORS .An Ed Schouten Aq Mt ed@FreeBSD.org Index: head/lib/libc/sys/procctl.2 =================================================================== --- head/lib/libc/sys/procctl.2 (revision 276005) +++ head/lib/libc/sys/procctl.2 (revision 276006) @@ -1,359 +1,359 @@ .\" Copyright (c) 2013 Advanced Computing Technologies LLC .\" Written by: John H. Baldwin .\" All rights reserved. .\" .\" Copyright (c) 2014 The FreeBSD Foundation .\" Portions of this documentation were written by Konstantin Belousov .\" under sponsorship from the FreeBSD Foundation. .\" .\" 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 AUTHOR 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 AUTHOR 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. .\" .\" $FreeBSD$ .\" .Dd December 16, 2014 .Dt PROCCTL 2 .Os .Sh NAME .Nm procctl .Nd control processes .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/procctl.h .Ft int .Fn procctl "idtype_t idtype" "id_t id" "int cmd" "void *arg" .Sh DESCRIPTION The .Fn procctl system call provides for control over processes. The .Fa idtype and .Fa id arguments specify the set of processes to control. If multiple processes match the identifier, .Nm will make a .Dq best effort to control as many of the selected processes as possible. An error is only returned if no selected processes successfully complete the request. The following identifier types are supported: .Bl -tag -width "Dv P_PGID" .It Dv P_PID Control the process with the process ID .Fa id . .It Dv P_PGID Control processes belonging to the process group with the ID .Fa id . .El .Pp The control request to perform is specified by the .Fa cmd argument. The following commands are supported: .Bl -tag -width "Dv PROC_REAP_GETPIDS" .It Dv PROC_SPROTECT Set process protection state. This is used to mark a process as protected from being killed if the system exhausts available memory and swap. The .Fa arg parameter must point to an integer containing an operation and zero or more optional flags. The following operations are supported: .Bl -tag -width "Dv PPROT_CLEAR" .It Dv PPROT_SET Mark the selected processes as protected. .It Dv PPROT_CLEAR Clear the protected state of selected processes. .El .Pp The following optional flags are supported: .Bl -tag -width "Dv PPROT_DESCE" .It Dv PPROT_DESCEND Apply the requested operation to all child processes of each selected process in addition to each selected process. .It Dv PPROT_INHERIT When used with .Dv PPROT_SET , mark all future child processes of each selected process as protected. Future child processes will also mark all of their future child processes. .El .It Dv PROC_REAP_ACQUIRE Acquires the reaper status for the current process. The status means that children orphaned by the reaper's descendants that were forked after the acquisition of the status are reparented to the reaper. After the system initialization, .Xr init 8 is the default reaper. -.Pp .It Dv PROC_REAP_RELEASE Releases the reaper state for the current process. The reaper of the current process becomes the new reaper of the current process's descendants. .It Dv PROC_REAP_STATUS Provides the information about the reaper of the specified process, or the process itself when it is a reaper. The .Fa data argument must point to a .Vt procctl_reaper_status structure which is filled in by the syscall on successful return. .Bd -literal struct procctl_reaper_status { u_int rs_flags; u_int rs_children; u_int rs_descendants; pid_t rs_reaper; pid_t rs_pid; }; .Ed The .Fa rs_flags may have the following flags returned: .Bl -tag -width "Dv REAPER_STATUS_REALINIT" .It Dv REAPER_STATUS_OWNED The specified process has acquired the reaper status and has not released it. When the flag is returned, the specified process .Fa id , pid, identifies the reaper, otherwise the .Fa rs_reaper field of the structure is set to the pid of the reaper for the specified process id. .It Dv REAPER_STATUS_REALINIT The specified process is the root of the reaper tree, i.e. .Xr init 8 . .El +.Pp The .Fa rs_children field returns the number of children of the reaper. The .Fa rs_descendants field returns the total number of descendants of the reaper(s), not counting descendants of the reaper in the subtree. The .Fa rs_reaper field returns the reaper pid. The .Fa rs_pid returns the pid of one reaper child if there are any descendants. .It Dv PROC_REAP_GETPIDS Queries the list of descendants of the reaper of the specified process. The request takes a pointer to a .Vt procctl_reaper_pids structure in the .Fa data parameter. .Bd -literal struct procctl_reaper_pids { u_int rp_count; struct procctl_reaper_pidinfo *rp_pids; }; .Ed When called, the .Fa rp_pids field must point to an array of .Vt procctl_reaper_pidinfo structures, to be filled in on return, and the .Fa rp_count field must specify the size of the array, into which no more than .Fa rp_count elements will be filled in by the kernel. .Pp The .Vt "struct procctl_reaper_pidinfo" structure provides some information about one of the reaper's descendants. Note that for a descendant that is not a child, it may be incorrectly identified because of a race in which the original child process exited and the exited process's pid was reused for an unrelated process. .Bd -literal struct procctl_reaper_pidinfo { pid_t pi_pid; pid_t pi_subtree; u_int pi_flags; }; .Ed The .Fa pi_pid field is the process id of the descendant. The .Fa pi_subtree field provides the pid of the child of the reaper, which is the (grand-)parent of the process. The .Fa pi_flags field returns the following flags, further describing the descendant: .Bl -tag -width "Dv REAPER_PIDINFO_VALID" .It Dv REAPER_PIDINFO_VALID Set to indicate that the .Vt procctl_reaper_pidinfo structure was filled in by the kernel. Zero-filling the .Fa rp_pids array and testing the .Dv REAPER_PIDINFO_VALID flag allows the caller to detect the end of the returned array. .It Dv REAPER_PIDINFO_CHILD The .Fa pi_pid field identifies the direct child of the reaper. .El .It Dv PROC_REAP_KILL Request to deliver a signal to some subset of the descendants of the reaper. The .Fa data parameter must point to a .Vt procctl_reaper_kill structure, which is used both for parameters and status return. .Bd -literal struct procctl_reaper_kill { int rk_sig; u_int rk_flags; pid_t rk_subtree; u_int rk_killed; pid_t rk_fpid; }; .Ed The .Fa rk_sig field specifies the signal to be delivered. Zero is not a valid signal number, unlike .Xr kill 2 . The .Fa rk_flags field further directs the operation. It is or-ed from the following flags: .Bl -tag -width "Dv REAPER_KILL_CHILDREN" .It Dv REAPER_KILL_CHILDREN Deliver the specified signal only to direct children of the reaper. .It Dv REAPER_KILL_SUBTREE Deliver the specified signal only to descendants that were forked by the direct child with pid specified in the .Fa rk_subtree field. .El If neither the .Dv REAPER_KILL_CHILDREN nor the .Dv REAPER_KILL_SUBTREE flags are specified, all current descendants of the reaper are signalled. .Pp If a signal was delivered to any process, the return value from the request is zero. In this case, the .Fa rk_killed field identifies the number of processes signalled. The .Fa rk_fpid field is set to the pid of the first process for which signal delivery failed, e.g. due to the permission problems. If no such process exist, the .Fa rk_fpid field is set to -1. .El .Sh RETURN VALUES If an error occurs, a value of -1 is returned and .Va errno is set to indicate the error. .Sh ERRORS The .Fn procctl system call will fail if: .Bl -tag -width Er .It Bq Er EFAULT The .Fa arg parameter points outside the process's allocated address space. .It Bq Er EINVAL The .Fa cmd argument specifies an unsupported command. .Pp The .Fa idtype argument specifies an unsupported identifier type. .It Bq Er EPERM The calling process does not have permission to perform the requested operation on any of the selected processes. .It Bq Er ESRCH No processes matched the requested .Fa idtype and .Fa id . .It Bq Er EINVAL An invalid operation or flag was passed in .Fa arg for a .Dv PROC_SPROTECT command. .It Bq Er EPERM The .Fa idtype argument is not equal to .Dv P_PID , or .Fa id is not equal to the pid of the calling process, for .Dv PROC_REAP_ACQUIRE or .Dv PROC_REAP_RELEASE requests. .It Bq Er EINVAL Invalid or undefined flags were passed to a .Dv PROC_REAP_KILL request. .It Bq Er EINVAL An invalid or zero signal number was requested for a .Dv PROC_REAP_KILL request. .It Bq Er EINVAL The .Dv PROC_REAP_RELEASE request was issued by the .Xr init 8 process. .It Bq Er EBUSY The .Dv PROC_REAP_ACQUIRE request was issued by a process that had already acquired reaper status and has not yet released it. .El .Sh SEE ALSO .Xr kill 2 , .Xr ptrace 2 , .Xr wait 2 , .Xr init 8 .Sh HISTORY The .Fn procctl function appeared in .Fx 10.0 . The reaper facility is based on a similar feature of Linux and DragonflyBSD, and first appeared in .Fx 10.2 . Index: head/lib/libc/sys/revoke.2 =================================================================== --- head/lib/libc/sys/revoke.2 (revision 276005) +++ head/lib/libc/sys/revoke.2 (revision 276006) @@ -1,106 +1,106 @@ .\" Copyright (c) 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Berkeley Software Design, Inc. .\" .\" 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. .\" 4. 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. .\" .\" @(#)revoke.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd June 4, 1993 .Dt REVOKE 2 .Os .Sh NAME .Nm revoke .Nd revoke file access .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft int .Fn revoke "const char *path" .Sh DESCRIPTION The .Fn revoke system call invalidates all current open file descriptors in the system for the file named by .Fa path . Subsequent operations on any such descriptors fail, with the exceptions that a .Fn read from a character device file which has been revoked returns a count of zero (end of file), and a .Fn close system call will succeed. If the file is a special file for a device which is open, the device close function is called as if all open references to the file had been closed. .Pp Access to a file may be revoked only by its owner or the super user. The .Fn revoke system call is currently supported only for block and character special device files. It is normally used to prepare a terminal device for a new login session, preventing any access by a previous user of the terminal. .Sh RETURN VALUES .Rv -std revoke .Sh ERRORS Access to the named file is revoked unless one of the following: .Bl -tag -width Er .It Bq Er ENOTDIR A component of the path prefix is not a directory. .It Bq Er ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire path name exceeded 1024 characters. .It Bq Er ENOENT The named file or a component of the path name does not exist. .It Bq Er EACCES Search permission is denied for a component of the path prefix. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .It Bq Er EFAULT The .Fa path argument points outside the process's allocated address space. .It Bq Er EINVAL The implementation does not support the .Fn revoke operation on the named file. .It Bq Er EPERM The caller is neither the owner of the file nor the super user. .El .Sh SEE ALSO -.Xr close 2 , -.Xr revoke 1 +.Xr revoke 1 , +.Xr close 2 .Sh HISTORY The .Fn revoke system call first appeared in .Bx 4.3 Reno . Index: head/lib/libc/sys/sched_setscheduler.2 =================================================================== --- head/lib/libc/sys/sched_setscheduler.2 (revision 276005) +++ head/lib/libc/sys/sched_setscheduler.2 (revision 276006) @@ -1,166 +1,166 @@ .\" $FreeBSD$ .\" Copyright (c) 1998 HD Associates, Inc. .\" 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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 March 12, 1998 .Dt SCHED_SETSCHEDULER 2 .Os .Sh NAME .Nm sched_setscheduler , .Nm sched_getscheduler .Nd set/get scheduling policy and scheduler parameters .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sched.h .Ft int .Fn sched_setscheduler "pid_t pid" "int policy" "const struct sched_param *param" .Ft int .Fn sched_getscheduler "pid_t pid" .Sh DESCRIPTION The .Fn sched_setscheduler system call sets the scheduling policy and scheduling parameters of the process specified by .Fa pid to .Fa policy and the parameters specified in the .Vt sched_param structure pointed to by .Fa param , respectively. The value of the .Fa sched_priority member in the .Fa param structure must be any integer within the inclusive priority range for the scheduling policy specified by .Fa policy . .Pp In this implementation, if the value of .Fa pid is negative the system call will fail. .Pp If a process specified by .Fa pid exists and if the calling process has permission, the scheduling policy and scheduling parameters will be set for the process whose process ID is equal to .Fa pid . .Pp If .Fa pid is zero, the scheduling policy and scheduling parameters are set for the calling process. .Pp In this implementation, the policy of when a process can affect the scheduling parameters of another process is specified in .St -p1003.1b-93 as a write-style operation. .Pp The scheduling policies are in .Fa : .Bl -tag -width [SCHED_OTHER] .It Bq Er SCHED_FIFO First-in-first-out fixed priority scheduling with no round robin scheduling; .It Bq Er SCHED_OTHER The standard time sharing scheduler; .It Bq Er SCHED_RR Round-robin scheduling across same priority processes. .El .Pp The .Vt sched_param structure is defined in .Fa : .Bd -literal -offset indent struct sched_param { int sched_priority; /* scheduling priority */ }; .Ed .Pp The .Fn sched_getscheduler system call returns the scheduling policy of the process specified by .Fa pid . .Pp If a process specified by .Fa pid exists and if the calling process has permission, the scheduling parameters for the process whose process ID is equal to .Fa pid are returned. .Pp In this implementation, the policy of when a process can obtain the scheduling parameters of another process are detailed in .St -p1003.1b-93 as a read-style operation. .Pp If .Fa pid is zero, the scheduling parameters for the calling process will be returned. In this implementation, the .Fa sched_getscheduler system call will fail if .Fa pid is negative. .Sh RETURN VALUES .Rv -std .Sh ERRORS On failure .Va errno will be set to the corresponding value: .Bl -tag -width Er .It Bq Er ENOSYS The system is not configured to support this functionality. .It Bq Er EPERM The requesting process doesn not have permission as detailed in .St -p1003.1b-93 . .It Bq Er ESRCH No process can be found corresponding to that specified by .Fa pid . .It Bq Er EINVAL The value of the .Fa policy argument is invalid, or one or more of the parameters contained in .Fa param is outside the valid range for the specified scheduling policy. .El .Sh SEE ALSO -.Xr sched_getparam 2 , .Xr sched_get_priority_max 2 , .Xr sched_get_priority_min 2 , +.Xr sched_getparam 2 , .Xr sched_rr_get_interval 2 , .Xr sched_setparam 2 , .Xr sched_yield 2 .Sh STANDARDS The .Fn sched_setscheduler and .Fn sched_getscheduler system calls conform to .St -p1003.1b-93 . Index: head/lib/libc/sys/sigwaitinfo.2 =================================================================== --- head/lib/libc/sys/sigwaitinfo.2 (revision 276005) +++ head/lib/libc/sys/sigwaitinfo.2 (revision 276006) @@ -1,206 +1,206 @@ .\" Copyright (c) 2005 David Xu .\" 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(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. .\" .\" $FreeBSD$ .\" .Dd September 27, 2012 .Dt SIGTIMEDWAIT 2 .Os .Sh NAME .Nm sigtimedwait , sigwaitinfo .Nd "wait for queued signals (REALTIME)" .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In signal.h .Ft int .Fo sigtimedwait .Fa "const sigset_t *restrict set" "siginfo_t *restrict info" .Fa "const struct timespec *restrict timeout" .Fc .Ft int .Fn sigwaitinfo "const sigset_t * restrict set" "siginfo_t * restrict info" .Sh DESCRIPTION The .Fn sigtimedwait system call is equivalent to .Fn sigwaitinfo except that if none of the signals specified by .Fa set are pending, .Fn sigtimedwait waits for the time interval specified in the .Vt timespec structure referenced by .Fa timeout . If the .Vt timespec structure pointed to by .Fa timeout is zero-valued and if none of the signals specified by .Fa set are pending, then .Fn sigtimedwait returns immediately with an error. If .Fa timeout is the .Dv NULL pointer, the behavior is unspecified. .Dv CLOCK_MONOTONIC clock is used to measure the time interval specified by the .Fa timeout argument. .Pp The .Fn sigwaitinfo system call selects the pending signal from the set specified by .Fa set . Should any of multiple pending signals in the range .Dv SIGRTMIN to .Dv SIGRTMAX be selected, it shall be the lowest numbered one. The selection order between realtime and non-realtime signals, or between multiple pending non-realtime signals, is unspecified. If no signal in .Fa set is pending at the time of the call, the calling thread is suspended until one or more signals in .Fa set become pending or until it is interrupted by an unblocked, caught signal. .Pp The .Fn sigwaitinfo system call is equivalent to the .Fn sigwait system call if the .Fa info argument is .Dv NULL . If the .Fa info argument is .Pf non- Dv NULL , the .Fn sigwaitinfo function is equivalent to .Fn sigwait , except that the selected signal number shall be stored in the .Va si_signo member, and the cause of the signal shall be stored in the .Va si_code member. Besides this, the .Fn sigwaitinfo and .Fn sigtimedwait system calls may return .Er EINTR if interrupted by signal, which is not allowed for the .Fn sigwait function. .Pp If any value is queued to the selected signal, the first such queued value is dequeued and, if the info argument is .Pf non- Dv NULL , the value is stored in the .Va si_value member of .Fa info . The system resource used to queue the signal is released and returned to the system for other use. If no value is queued, the content of the .Va si_value member is zero-valued. If no further signals are queued for the selected signal, the pending indication for that signal is reset. .Sh RETURN VALUES Upon successful completion (that is, one of the signals specified by .Fa set is pending or is generated) .Fn sigwaitinfo and .Fn sigtimedwait return the selected signal number. Otherwise, the functions return a value of \-1 and set the global variable .Va errno to indicate the error. .Sh ERRORS The .Fn sigtimedwait system call will fail if: .Bl -tag -width Er .It Bq Er EAGAIN No signal specified by set was generated within the specified timeout period. .El .Pp The .Fn sigtimedwait and .Fn sigwaitinfo system calls fail if: .Bl -tag -width Er .It Bq Er EINTR The wait was interrupted by an unblocked, caught signal. -.Pp .El +.Pp The .Fn sigtimedwait system call may also fail if: .Bl -tag -width Er .It Bq Er EINVAL The .Fa timeout argument specified a .Va tv_nsec value less than zero or greater than or equal to 1000 million. Kernel only checks for this error if no signal is pending in set and it is necessary to wait. .El .Sh SEE ALSO .Xr sigaction 2 , .Xr sigpending 2 , .Xr sigqueue 2 , .Xr sigsuspend 2 , .Xr sigwait 2 , .Xr pause 3 , .Xr pthread_sigmask 3 , .Xr siginfo 3 .Sh STANDARDS The .Fn sigtimedwait and .Fn sigwaitinfo system calls conform to .St -p1003.1-96 . Index: head/lib/libc/sys/vfork.2 =================================================================== --- head/lib/libc/sys/vfork.2 (revision 276005) +++ head/lib/libc/sys/vfork.2 (revision 276006) @@ -1,129 +1,129 @@ .\" Copyright (c) 1980, 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. .\" 4. 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. .\" .\" @(#)vfork.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd November 13, 2009 .Dt VFORK 2 .Os .Sh NAME .Nm vfork .Nd create a new process without copying the address space .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft pid_t .Fn vfork void .Sh DESCRIPTION The .Fn vfork system call can be used to create new processes without fully copying the address space of the old process, which is horrendously inefficient in a paged environment. It is useful when the purpose of .Xr fork 2 would have been to create a new system context for an .Xr execve 2 . The .Fn vfork system call differs from .Xr fork 2 in that the child borrows the parent's memory and thread of control until a call to .Xr execve 2 or an exit (either by a call to .Xr _exit 2 or abnormally). The parent process is suspended while the child is using its resources. .Pp The .Fn vfork system call returns 0 in the child's context and (later) the pid of the child in the parent's context. .Pp The .Fn vfork system call can normally be used just like .Xr fork 2 . It does not work, however, to return while running in the child's context from the procedure that called .Fn vfork since the eventual return from .Fn vfork would then return to a no longer existent stack frame. Be careful, also, to call .Xr _exit 2 rather than .Xr exit 3 if you cannot .Xr execve 2 , since .Xr exit 3 will flush and close standard I/O channels, and thereby mess up the parent processes standard I/O data structures. (Even with .Xr fork 2 it is wrong to call .Xr exit 3 since buffered data would then be flushed twice.) .Sh RETURN VALUES Same as for .Xr fork 2 . .Sh SEE ALSO -.Xr execve 2 , .Xr _exit 2 , +.Xr execve 2 , .Xr fork 2 , .Xr rfork 2 , .Xr sigaction 2 , .Xr wait 2 , .Xr exit 3 .Sh HISTORY The .Fn vfork system call appeared in .Bx 2.9 . .Sh BUGS To avoid a possible deadlock situation, processes that are children in the middle of a .Fn vfork are never sent .Dv SIGTTOU or .Dv SIGTTIN signals; rather, output or .Xr ioctl 2 calls are allowed and input attempts result in an end-of-file indication.