Index: head/lib/libarchive/libarchive-formats.5 =================================================================== --- head/lib/libarchive/libarchive-formats.5 (revision 147401) +++ head/lib/libarchive/libarchive-formats.5 (revision 147402) @@ -1,243 +1,244 @@ .\" Copyright (c) 2003-2004 Tim Kientzle .\" 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 April 27, 2004 .Dt libarchive-formats 3 .Os .Sh NAME .Nm libarchive-formats .Nd archive formats supported by the libarchive library .Sh DESCRIPTION The .Xr libarchive 3 library reads and writes a variety of streaming archive formats. Generally speaking, all of these archive formats consist of a series of .Dq entries . Each entry stores a single file system object, such as a file, directory, or symbolic link. .Pp The following provides a brief description of each format supported by libarchive, with some information about recognized extensions or limitations of the current library support. Note that just because a format is supported by libarchive does not imply that a program that uses libarchive will support that format. Applications that use libarchive specify which formats they wish to support. .Ss Tar Formats The .Xr libarchive 3 library can read most tar archives. However, it only writes POSIX-standard .Dq ustar and .Dq pax interchange formats. .Pp All tar formats store each entry in one or more 512-byte records. The first record is used for file metadata, including filename, timestamp, and mode information, and the file data is stored in subsequent records. Later variants have extended this by either appropriating undefined areas of the header record, extending the header to multiple records, or by storing special entries that modify the interpretation of subsequent entries. .Pp .Bl -tag -width indent .It Cm gnutar The .Xr libarchive 3 library can read GNU-format tar archives. It currently supports the most popular GNU extensions, including modern long filename and linkname support, as well as atime and ctime data. The libarchive library does not support sparse files, multi-volume archives, nor the old GNU long filename format. .It Cm pax The .Xr libarchive 3 library can read and write POSIX-compliant pax interchange format archives. Pax interchange format archives are an extension of the older ustar format that adds a separate entry with additional attributes stored as key/value pairs. The presence of this additional entry is the only difference between pax interchange format and the older ustar format. The extended attributes are of unlimited length and are stored as UTF-8 Unicode strings. Keywords defined in the standard are in all lowercase; vendors are allowed to define custom keys by preceding them with the vendor name in all uppercase. When writing pax archives, libarchive uses many of the SCHILY keys defined by Joerg Schilling's .Dq star archiver. The libarchive library can read most of the SCHILY keys. It ignores any keywords that it does not understand. .It Cm restricted pax The libarchive library can also write pax archives in which it attempts to suppress the extended attributes entry whenever possible. The result will be identical to a ustar archive unless the extended attributes entry is required to store a long file name, long linkname, extended ACL, file flags, or if any of the standard ustar data (user name, group name, UID, GID, etc) cannot be fully represented in the ustar header. In all cases, the result can be dearchived by any program that can read POSIX-compliant pax interchange format archives. .It Cm ustar The libarchive library can both read and write this format. This format has the following limitations: .Bl -bullet -compact .It Device major and minor numbers are limited to 21 bits. Nodes with larger numbers will not be added to the archive. .It Path names in the archive are limited to 255 bytes. (Shorter if there is no / character in exactly the right place.) .It Symbolic links and hard links are stored in the archive with the name of the referenced file. This name is limited to 100 bytes. .It Extended attributes, file flags, and other extended security information cannot be stored. .It Archive entries are limited to 2 gigabytes in size. .El Note that the pax interchange format has none of these restrictions. .El .Pp The libarchive library can also read a variety of commonly-used extensions to the basic tar format. In particular, it supports base-256 values in certain numeric fields. This essentially removes the limitations on file size, modification time, and device numbers. .Pp The first tar program appeared in Sixth Edition Unix (circa 1976). This makes the tar format one of the oldest and most widely-supported archive formats. The first official standard for the tar file format was the .Dq ustar (Unix Standard Tar) format defined by POSIX in 1988. POSIX.1-2001 extended the ustar format to create the .Dq pax interchange format. There have also been many custom variations. .Ss Cpio Formats The libarchive library can read a number of common cpio variants and can write .Dq odc format archives. A cpio archive stores each entry as a fixed-size header followed by a variable-length filename and variable-length data. Unlike tar, cpio does only minimal padding of the header or file data. There are a variety of cpio formats, which differ primarily in how they store the initial header: some store the values as octal or hexadecimal numbers in ASCII, others as binary values of varying byte order and length. .Bl -tag -width indent .It Cm binary The libarchive library can read both big-endian and little-endian variants of the original binary cpio format. This format used 32-bit binary values for file size and mtime, and 16-bit binary values for the other fields. .It Cm odc The libarchive library can both read and write this POSIX-standard format. This format stores the header contents as octal values in ASCII. It is standard, portable, and immune from byte-order confusion. File sizes and mtime are limited to 33 bits (8GB file size), other fields are limited to 18 bits. .It Cm SVR4 The libarchive library can read both CRC and non-CRC variants of this format. The SVR4 format uses eight-digit hexadecimal values for all header fields. This limits file size to 4GB, and also limits the mtime and other fields to 32 bits. The SVR4 format can optionally include a CRC of the file contents, although libarchive does not currently verify this CRC. .El .Pp Cpio is an old format that was widely used because of its simplicity and its support for very long filenames. Unfortunately, it has many limitations that make it unsuitable for widespread use. Only the POSIX format permits files over 4GB, and its 18-bit limit for most other fields makes it unsuitable for modern systems. In addition, cpio formats only store numeric UID/GID values (not usernames and group names), which can make it very difficult to correctly transfer archives across systems. Finally, there is no good way to extend the format, which means that ACLs, file flags, character encoding information, and non-standard file types can not be added except by breaking compatibility with existing implementations. .Ss Shar Formats A .Dq shell archive is a shell script that, when executed on a POSIX-compliant system, will recreate a collection of file system objects. The libarchive library can write two different kinds of shar archives: .Bl -tag -width indent .It Cm shar The traditional shar format uses a limited set of POSIX commands, including .Xr echo 1 , .Xr mkdir 1 , and .Xr sed 1 . It is suitable for portably archiving small collections of plain text files. However, it is not generally well-suited for large archives (many implementations of .Xr sh 1 have limits on the size of a script) nor should it be used with non-text files. .It Cm shardump This format is similar to shar but encodes files using .Xr uuencode 1 so that the result will be a plain text file regardless of the file contents. It also includes additional shell commands that attempt to reproduce as many file attributes as possible, including owner, mode, and flags. The additional commands used to restore file attributes make shardump archives less portable than plain shar archives. .El .Ss ISO9660 format Libarchive can read and extract from files containing ISO9660-compliant -CDROM images. It also has partial support for Rockridge extensions. +CDROM images. +It also has partial support for Rockridge extensions. In many cases, this can remove the need to burn a physical CDROM. It also avoids security and complexity issues that come with virtual mounts and loopback devices. .Ss Zip format Libarchive can extract from most zip format archives. It currently only supports uncompressed entries and entries compressed with the .Dq deflate algorithm. Older zip compression algorithms are not supported. .Sh SEE ALSO .Xr cpio 1 , .Xr mkisofs 1 , .Xr shar 1 , .Xr tar 1 , .Xr zip 1 , .Xr zlib 3 , .Xr tar 5 Index: head/lib/libarchive/tar.5 =================================================================== --- head/lib/libarchive/tar.5 (revision 147401) +++ head/lib/libarchive/tar.5 (revision 147402) @@ -1,715 +1,715 @@ .\" Copyright (c) 2003-2004 Tim Kientzle .\" 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 May 20, 2004 .Dt TAR 5 .Os .Sh NAME .Nm tar .Nd format of tape archive files .Sh DESCRIPTION The .Nm archive format collects any number of files, directories, and other file system objects (symbolic links, device nodes, etc.) into a single stream of bytes. The format was originally designed to be used with tape drives that operate with fixed-size blocks, but is widely used as a general packaging mechanism. .Ss General Format A .Nm archive consists of a series of 512-byte records. Each file system object requires a header record which stores basic metadata (pathname, owner, permissions, etc.) and zero or more records containing any file data. The end of the archive is indicated by two records consisting entirely of zero bytes. .Pp For compatibility with tape drives that use fixed block sizes, programs that read or write tar files always read or write a fixed number of records with each I/O operation. These .Dq blocks are always a multiple of the record size. The most common block size\(emand the maximum supported by historic implementations\(emis 10240 bytes or 20 records. (Note: the terms .Dq block and .Dq record here are not entirely standard; this document follows the convention established by John Gilmore in documenting .Nm pdtar . ) .Ss Old-Style Archive Format The original tar archive format has been extended many times to include additional information that various implementors found necessary. This section describes the variant implemented by the tar command included in .At v7 , which is one of the earliest widely-used versions of the tar program. .Pp The header record for an old-style .Nm archive consists of the following: .Bd -literal -offset indent struct header_old_tar { char name[100]; char mode[8]; char uid[8]; char gid[8]; char size[12]; char mtime[12]; char checksum[8]; char linkflag[1]; char linkname[100]; char pad[255]; }; .Ed All unused bytes in the header record are filled with nulls. .Bl -tag -width indent .It Va name Pathname, stored as a null-terminated string. Early tar implementations only stored regular files (including hardlinks to those files). One common early convention used a trailing "/" character to indicate a directory name, allowing directory permissions and owner information to be archived and restored. .It Va mode File mode, stored as an octal number in ASCII. .It Va uid , Va gid User id and group id of owner, as octal numbers in ASCII. .It Va size Size of file, as octal number in ASCII. For regular files only, this indicates the amount of data that follows the header. In particular, this field was ignored by early tar implementations when extracting hardlinks. Modern writers should always store a zero length for hardlink entries. .It Va mtime Modification time of file, as an octal number in ASCII. This indicates the number of seconds since the start of the epoch, 00:00:00 UTC January 1, 1970. Note that negative values should be avoided here, as they are handled inconsistently. .It Va checksum Header checksum, stored as an octal number in ASCII. To compute the checksum, set the checksum field to all spaces, then sum all bytes in the header using unsigned arithmetic. This field should be stored as six octal digits followed by a null and a space character. Note that many early implementations of tar used signed arithmetic for the checksum field, which can cause interoperability problems when transferring archives between systems. Modern robust readers compute the checksum both ways and accept the header if either computation matches. .It Va linkflag , Va linkname In order to preserve hardlinks and conserve tape, a file with multiple links is only written to the archive the first time it is encountered. The next time it is encountered, the .Va linkflag is set to an ASCII .Sq 1 and the .Va linkname field holds the first name under which this file appears. (Note that regular files have a null value in the .Va linkflag field.) .El .Pp Early tar implementations varied in how they terminated these fields. The tar command in .At v7 used the following conventions (this is also documented in early BSD manpages): the pathname must be null-terminated; the mode, uid, and gid fields must end in a space and a null byte; the size and mtime fields must end in a space; the checksum is terminated by a null and a space. Early implementations filled the numeric fields with leading spaces. This seems to have been common practice until the .St -p1003.1 standard was released. For best portability, modern implementations should fill the numeric fields with leading zeros. .Ss Pre-POSIX Archives An early draft of .St -p1003.1-88 served as the basis for John Gilmore's .Nm pdtar program and many system implementations from the late 1980s and early 1990s. These archives generally follow the POSIX ustar format described below with the following variations: .Bl -bullet -compact -width indent .It The magic value is .Dq ustar\ \& (note the following space). The version field contains a space character followed by a null. .It The numeric fields are generally filled with leading spaces (not leading zeros as recommended in the final standard). .It The prefix field is often not used, limiting pathnames to the 100 characters of old-style archives. .El .Ss POSIX ustar Archives .St -p1003.1-88 defined a standard tar file format to be read and written by compliant implementations of .Xr tar 1 and .Xr pax 1 . This format is often called the .Dq ustar format, after the magic value used in the header. (The name is an acronym for -.Dq Unix Standard TAR. ) +.Dq Unix Standard TAR . ) It extends the historic format with new fields: .Bd -literal -offset indent struct header_posix_ustar { char name[100]; char mode[8]; char uid[8]; char gid[8]; char size[12]; char mtime[12]; char checksum[8]; char typeflag[1]; char linkname[100]; char magic[6]; char version[2]; char uname[32]; char gname[32]; char devmajor[8]; char devminor[8]; char prefix[155]; char pad[12]; }; .Ed .Bl -tag -width indent .It Va typeflag Type of entry. POSIX extended the earlier .Va linkflag field with several new type values: .Bl -tag -width indent -compact .It Dq 0 Regular file. NULL should be treated as a synonym, for compatibility purposes. .It Dq 1 Hard link. .It Dq 2 Symbolic link. .It Dq 3 Character device node. .It Dq 4 Block device node. .It Dq 5 Directory. .It Dq 6 FIFO node. .It Dq 7 Reserved. .It Other A POSIX-compliant implementation must treat any unrecognized typeflag value as a regular file. In particular, writers should ensure that all entries have a valid filename so that they can be restored by readers that do not support the corresponding extension. Uppercase letters "A" through "Z" are reserved for custom extensions. Note that sockets and whiteout entries are not archivable. .El It is worth noting that the .Va size field, in particular, has different meanings depending on the type. For regular files, of course, it indicates the amount of data following the header. For directories, it may be used to indicate the total size of all files in the directory, for use by operating systems that pre-allocate directory space. For all other types, it should be set to zero by writers and ignored by readers. .It Va magic Contains the magic value .Dq ustar followed by a NULL byte to indicate that this is a POSIX standard archive. Full compliance requires the uname and gname fields be properly set. .It Va version Version. This should be .Dq 00 (two copies of the ASCII digit zero) for POSIX standard archives. .It Va uname , Va gname User and group names, as null-terminated ASCII strings. These should be used in preference to the uid/gid values when they are set and the corresponding names exist on the system. .It Va devmajor , Va devminor Major and minor numbers for character device or block device entry. .It Va prefix First part of pathname. If the pathname is too long to fit in the 100 bytes provided by the standard format, it can be split at any .Pa / character with the first portion going here. If the prefix field is not empty, the reader will prepend the prefix value and a .Pa / character to the regular name field to obtain the full pathname. .El .Pp Note that all unused bytes must be set to .Dv NULL . .Pp Field termination is specified slightly differently by POSIX than by previous implementations. The .Va magic , .Va uname , and .Va gname fields must have a trailing .Dv NULL . The .Va pathname , .Va linkname , and .Va prefix fields must have a trailing .Dv NULL unless they fill the entire field. (In particular, it is possible to store a 256-character pathname if it happens to have a .Pa / as the 156th character.) POSIX requires numeric fields to be zero-padded in the front, and allows them to be terminated with either space or .Dv NULL characters. .Pp Currently, most tar implementations comply with the ustar format, occasionally extending it by adding new fields to the blank area at the end of the header record. .Ss Pax Interchange Format There are many attributes that cannot be portably stored in a POSIX ustar archive. .St -p1003.1-2001 defined a .Dq pax interchange format that uses two new types of entries to hold text-formatted metadata that applies to following entries. Note that a pax interchange format archive is a ustar archive in every respect. The new data is stored in ustar-compatible archive entries that use the .Dq x or .Dq g typeflag. In particular, older implementations that do not fully support these extensions will extract the metadata into regular files, where the metadata can be examined as necessary. .Pp An entry in a pax interchange format archive consists of one or two standard ustar entries, each with its own header and data. The first optional entry stores the extended attributes for the following entry. This optional first entry has an "x" typeflag and a size field that indicates the total size of the extended attributes. The extended attributes themselves are stored as a series of text-format lines encoded in the portable UTF-8 encoding. Each line consists of a decimal number, a space, a key string, an equals sign, a value string, and a new line. The decimal number indicates the length of the entire line, including the initial length field and the trailing newline. An example of such a field is: .Dl 25 ctime=1084839148.1212\en Keys in all lowercase are standard keys. Vendors can add their own keys by prefixing them with an all uppercase vendor name and a period. Note that, unlike the historic header, numeric values are stored using decimal, not octal. A description of some common keys follows: .Bl -tag -width indent .It Cm atime , Cm ctime , Cm mtime File access, inode change, and modification times. These fields can be negative or include a decimal point and a fractional value. .It Cm uname , Cm uid , Cm gname , Cm gid User name, group name, and numeric UID and GID values. The user name and group name stored here are encoded in UTF8 and can thus include non-ASCII characters. The UID and GID fields can be of arbitrary length. .It Cm linkpath The full path of the linked-to file. Note that this is encoded in UTF8 and can thus include non-ASCII characters. .It Cm path The full pathname of the entry. Note that this is encoded in UTF8 and can thus include non-ASCII characters. .It Cm realtime.* , Cm security.* These keys are reserved and may be used for future standardization. .It Cm size The size of the file. Note that there is no length limit on this field, allowing conforming archives to store files much larger than the historic 8GB limit. .It Cm SCHILY.* Vendor-specific attributes used by Joerg Schilling's .Nm star implementation. .It Cm SCHILY.acl.access , Cm SCHILY.acl.default Stores the access and default ACLs as textual strings in a format that is an extension of the format specified by POSIX.1e draft 17. In particular, each user or group access specification can include a fourth colon-separated field with the numeric UID or GID. This allows ACLs to be restored on systems that may not have complete user or group information available (such as when NIS/YP or LDAP services are temporarily unavailable). .It Cm SCHILY.devminor , Cm SCHILY.devmajor The full minor and major numbers for device nodes. .It Cm SCHILY.dev, Cm SCHILY.ino , Cm SCHILY.nlinks The device number, inode number, and link count for the entry. In particular, note that a pax interchange format archive using Joerg Schilling's .Cm SCHILY.* extensions can store all of the data from .Va struct stat . .It Cm VENDOR.* XXX document other vendor-specific extensions XXX .El .Pp Any values stored in an extended attribute override the corresponding values in the regular tar header. Note that compliant readers should ignore the regular fields when they are overridden. This is important, as existing archivers are known to store non-compliant values in the standard header fields in this situation. There are no limits on length for any of these fields. In particular, numeric fields can be arbitrarily large. All text fields are encoded in UTF8. Compliant writers should store only portable 7-bit ASCII characters in the standard ustar header and use extended attributes whenever a text value contains non-ASCII characters. .Pp In addition to the .Cm x entry described above, the pax interchange format also supports a .Cm g entry. The .Cm g entry is identical in format, but specifies attributes that serve as defaults for all subsequent archive entries. The .Cm g entry is not widely used. .Pp Besides the new .Cm x and .Cm g entries, the pax interchange format has a few other minor variations from the earlier ustar format. The most troubling one is that hardlinks are permitted to have data following them. This allows readers to restore any hardlink to a file without having to rewind the archive to find an earlier entry. However, it creates complications for robust readers, as it is no longer clear whether or not they should ignore the size field for hardlink entries. .Ss GNU Tar Archives The GNU tar program started with a pre-POSIX format similar to that described earlier and has extended it using several different mechanisms: It added new fields to the empty space in the header (some of which was later used by POSIX for conflicting purposes); it allowed the header to be continued over multiple records; and it defined new entries that modify following entries (similar in principle to the .Cm x entry described above, but each GNU special entry is single-purpose, unlike the general-purpose .Cm x entry). As a result, GNU tar archives are not POSIX compatible, although more lenient POSIX-compliant readers can successfully extract most GNU tar archives. .Bd -literal -offset indent struct header_gnu_tar { char name[100]; char mode[8]; char uid[8]; char gid[8]; char size[12]; char mtime[12]; char checksum[8]; char typeflag[1]; char linkname[100]; char magic[6]; char version[2]; char uname[32]; char gname[32]; char devmajor[8]; char devminor[8]; char atime[12]; char ctime[12]; char offset[12]; char longnames[4]; char unused[1]; struct { char offset[12]; char numbytes[12]; } sparse[4]; char isextended[1]; char realsize[12]; char pad[17]; }; .Ed .Bl -tag -width indent .It Va typeflag GNU tar uses the following special entry types, in addition to those defined by POSIX: .Bl -tag -width indent .It "7" GNU tar treats type "7" records identically to type "0" records, except on one obscure RTOS where they are used to indicate the pre-allocation of a contiguous file on disk. .It "D" This indicates a directory entry. Unlike the POSIX-standard "5" typeflag, the header is followed by data records listing the names of files in this directory. Each name is preceded by an ASCII "Y" if the file is stored in this archive or "N" if the file is not stored in this archive. Each name is terminated with a null, and an extra null marks the end of the name list. The purpose of this entry is to support incremental backups; a program restoring from such an archive may wish to delete files on disk that did not exist in the directory when the archive was made. .Pp Note that the "D" typeflag specifically violates POSIX, which requires that unrecognized typeflags be restored as normal files. In this case, restoring the "D" entry as a file could interfere with subsequent creation of the like-named directory. .It "K" The data for this entry is a long linkname for the following regular entry. .It "L" The data for this entry is a long pathname for the following regular entry. .It "M" This is a continuation of the last file on the previous volume. GNU multi-volume archives guarantee that each volume begins with a valid entry header. To ensure this, a file may be split, with part stored at the end of one volume, and part stored at the beginning of the next volume. The "M" typeflag indicates that this entry continues an existing file. Such entries can only occur as the first or second entry in an archive (the latter only if the first entry is a volume label). The .Va size field specifies the size of this entry. The .Va offset field at bytes 369-380 specifies the offset where this file fragment begins. The .Va realsize field specifies the total size of the file (which must equal .Va size plus .Va offset ) . When extracting, GNU tar checks that the header file name is the one it is expecting, that the header offset is in the correct sequence, and that the sum of offset and size is equal to realsize. FreeBSD's version of GNU tar does not handle the corner case of an archive's being continued in the middle of a long name or other extension header. .It "N" Type "N" records are no longer generated by GNU tar. They contained a list of files to be renamed or symlinked after extraction; this was originally used to support long names. The contents of this record are a text description of the operations to be done, in the form .Dq Rename %s to %s\en or .Dq Symlink %s to %s\en ; in either case, both filenames are escaped using K&R C syntax. .It "S" This is a .Dq sparse regular file. Sparse files are stored as a series of fragments. The header contains a list of fragment offset/length pairs. If more than four such entries are required, the header is extended as necessary with .Dq extra header extensions (an older format that is no longer used), or .Dq sparse extensions. .It "V" The .Va name field should be interpreted as a tape/volume header name. This entry should generally be ignored on extraction. .El .It Va magic The magic field holds the five characters .Dq ustar followed by a space. Note that POSIX ustar archives have a trailing null. .It Va version The version field holds a space character followed by a null. Note that POSIX ustar archives use two copies of the ASCII digit .Dq 0 . .It Va atime , Va ctime The time the file was last accessed and the time of last change of file information, stored in octal as with .Va mtime. .It Va longnames This field is apparently no longer used. .It Sparse Va offset / Va numbytes Each such structure specifies a single fragment of a sparse file. The two fields store values as octal numbers. The fragments are each padded to a multiple of 512 bytes in the archive. On extraction, the list of fragments is collected from the header (including any extension headers), and the data is then read and written to the file at appropriate offsets. .It Va isextended If this is set to non-zero, the header will be followed by additional .Dq sparse header records. Each such record contains information about as many as 21 additional sparse blocks as shown here: .Bd -literal -offset indent struct gnu_sparse_header { struct { char offset[12]; char numbytes[12]; } sparse[21]; char isextended[1]; char padding[7]; }; .Ed .It Va realsize A binary representation of the file's complete size, with a much larger range than the POSIX file size. In particular, with .Cm M type files, the current entry is only a portion of the file. In that case, the POSIX size field will indicate the size of this entry; the .Va realsize field will indicate the total size of the file. .El .Ss Solaris Tar XXX More Details Needed XXX .Pp Solaris tar (beginning with SunOS XXX 5.7 ?? XXX) supports an .Dq extended format that is fundamentally similar to pax interchange format, with the following differences: .Bl -bullet -compact -width indent .It Extended attributes are stored in an entry whose type is .Cm X , not .Cm x , as used by pax interchange format. The detailed format of this entry appears to be the same as detailed above for the .Cm x entry. .It An additional .Cm A entry is used to store an ACL for the following regular entry. The body of this entry contains a seven-digit octal number (whose value is 01000000 plus the number of ACL entries) followed by a zero byte, followed by the textual ACL description. .El .Ss Other Extensions One common extension, utilized by GNU tar, star, and other newer .Nm implementations, permits binary numbers in the standard numeric fields. This is flagged by setting the high bit of the first character. This permits 95-bit values for the length and time fields and 63-bit values for the uid, gid, and device numbers. GNU tar supports this extension for the length, mtime, ctime, and atime fields. Joerg Schilling's star program supports this extension for all numeric fields. Note that this extension is largely obsoleted by the extended attribute record provided by the pax interchange format. .Pp Another early GNU extension allowed base-64 values rather than octal. This extension was short-lived and such archives are almost never seen. However, there is still code in GNU tar to support them; this code is responsible for a very cryptic warning message that is sometimes seen when GNU tar encounters a damaged archive. .Sh SEE ALSO .Xr ar 1 , .Xr pax 1 , .Xr tar 1 .Sh STANDARDS The .Nm tar utility is no longer a part of POSIX or the Single Unix Standard. It last appeared in .St -susv2 . It has been supplanted in subsequent standards by .Xr pax 1 . The ustar format is currently part of the specification for the .Xr pax 1 utility. The pax interchange file format is new with .St -p1003.1-2001 . .Sh HISTORY A .Nm tar command appeared in Seventh Edition Unix, which was released in January, 1979. It replaced the .Nm tp program from Fourth Edition Unix which in turn replaced the .Nm tap program from First Edition Unix. John Gilmore's .Nm pdtar public-domain implementation (circa 1987) was highly influential and formed the basis of GNU tar. Joerg Shilling's .Nm star archiver is another open-source (GPL) archiver (originally developed circa 1985) which features complete support for pax interchange format. Index: head/lib/libautofs/libautofs.3 =================================================================== --- head/lib/libautofs/libautofs.3 (revision 147401) +++ head/lib/libautofs/libautofs.3 (revision 147402) @@ -1,257 +1,265 @@ .\" Copyright (c) 2004 Alfred Perlstein .\" 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. .\" .\" $Id: libautofs.3,v 1.4 2004/09/08 08:12:21 bright Exp $ .\" $FreeBSD$ .Dd September 9, 2004 .Dt LIBAUTOFS 3 .Os .Sh NAME .Nm libautofs .Nd "procedural interface to managing an autofs file system" .Sh SYNOPSIS .In libautofs.h .Ft int .Fn autoh_get "const char *path" "autoh_t *hndlp" .Ft void .Fn autoh_free "autoh_t hndl" .Ft int .Fn autoh_getall "autoh_t **hndlpp" "int *cnt" .Ft void .Fn autoh_freeall "autoh_t *hndlep" .Ft int .Fn autoh_fd "autoh_t hndl" .Ft const char * .Fn autoh_mp "autoh_t hndl" .Ft int .Fn autoreq_get "autoh_t hndl" "autoreq_t **reqpp" "int *cntp" .Ft void .Fn autoreq_free "autoh_t hndl" "autoreq_t *reqp" .Ft int .Fn autoreq_serv "autoh_t hndl" "autoreq_t req" .Ft enum autoreq_op .Fn autoreq_getop "autoreq_t req" .Ft const char * .Fn autoreq_getpath "autoreq_t req" .Ft autoino_t .Fn autoreq_getino "autoreq_t req" .Ft autoino_t .Fn autoreq_getdirino "autoreq_t req" .Ft void .Fn autoreq_getaux "autoreq_t req" "void **auxdatap" "size_t *auxsizep" .Ft void .Fn autoreq_getoffset "autoreq_t req" "off_t *offp" .Ft void .Fn autoreq_getxid "autoreq_t req" "int *xidp" .Ft void .Fn autoreq_setino "autoreq_t req" "autoino_t ino" .Ft void .Fn autoreq_seterrno "autoreq_t req" "int errno" .Ft void .Fn autoreq_setaux "autoreq_t req" "void *auxdata" "size_t auxsize" .Ft void .Fn autoreq_seteof "autoreq_t req" "int eof" .Ft int .Fn autoh_togglepath "autoh_t hndl" "int toggle" "pid_t pid" "const char *path" .Ft int .Fn autoh_togglefd "autoh_t hndl" "int toggle" "pid_t pid" "int fd" .Sh DESCRIPTION The .Nm libautofs libarary provides a "mostly" stable interface to the .Xr autofs 9 file system. .Pp The inteface to .Xr autofs 9 is managed via handles of type .Fa autoh_t and .Fa autoreq_t which refer to handles to .Xr autofs 9 mount points and requests respectively. .Pp The .Fn autoh_get function returns a handle to an .Xr autofs 9 file system based on the .Fa path parameter. The handle returned should be freed via the .Fn autoh_free function. .Pp The .Fn autoh_getall function returns an array of handles to all mounted .Xr autofs 9 file systems, each of which should be released via the .Fn autoh_free function or released en-mass via the .Fn autoh_freeall function. .Pp The .Fn autoh_fd function returns a file descriptor that can be used with .Xr select 2 or .Xr poll 2 to check for "exceptional" data to detect an .Xr autofs 9 event. Users of .Xr select 2 should set the fd in the .Fa exceptfds fd_set. Users of .Xr poll 2 should set POLLPRI in the pollfd .Fa fds argument. .Pp The .Fn autoh_mp function returns the path to the autofs file system that the .Fa hndl is derived from. .Pp The .Fn autoreq_get function returns an array of autofs requests in .Fa reqpp , the number of requests is stored into .Fa cntp . Each request should be released using the .Fn autoreq_free function. .Pp Requests that are retrieved via the .Fn autoreq_get are served via the "autoreq_" functions. .Pp The following functions returns information about the request. .Bl -tag -width indent .It Fn autoreq_getop return the operation type of the request, that would be one of AUTOREQ_OP_UNKNOWN, AUTOREQ_OP_LOOKUP, AUTOREQ_OP_STAT, AUTOREQ_OP_READDIR depending on the type of request that .Xr autofs 9 requires service from. .It Fn autoreq_getpath return the path of the mountpoint associated with the request .Fa req . .It Fn autoreq_getino return the inode associated with the request .Fa req . .It Fn autoreq_getdirno return the directory inode associated with the request .Fa req . .It Fn autoreq_getaux return the auxilliray data associated with the request .Fa req . .It Fn autoreq_getoffset return the offset request associated with the request .Fa req . (used for readdir request) .It Fn autoreq_getxid return the transaction id associated with an autofs request, these -are unique per mount point, but not system wide. They can be used +are unique per mount point, but not system wide. +They can be used for debugging to ensure requests are being accepted by the kernel. .El .Pp The following functions allow one to set the response sent to .Xr autofs 9 to the requesting userland application. .Bl -tag -width indent .It Fn autoreq_setino Set the request .Fa req inode to .Fa ino , this is typically unused. .It Fn autoreq_seterrno set the error returned to the application sending the request, typically this is left alone, or set to ENOENT if the request is for a non-existant -name. The default error is no error. Meaning the application will see +name. +The default error is no error. +Meaning the application will see a successful return. .It Fn autoreq_setaux used to set the auxilliray data for a request, currently used to set -the dirent structures for serving a readdir request. Default is no +the dirent structures for serving a readdir request. +Default is no auxilliary data. .It Fn autoreq_seteof used to set the eof flag for readdir requests (default is not eof.) .El .Pp The functions .Fn autoh_togglepath and .Fn autoh_togglefd are used to set options on an .Xr autofs 9 directory via .Fa path and .Fa fd -respectively. The +respectively. +The .Fa pid argument should be set to the pid of the process serving .Xr autofs 9 -requests, or -1 to disable the option. The options are +requests, or -1 to disable the option. +The options are .Bl -tag -width AUTO_INDIRECT .It Fa AUTO_MOUNTER set this process as the one responsible for the .Xr autofs 9 node, if this process exits, then requests into the autofs will begin to fail. .It Fa AUTO_BROWSE dispatch directory read requests for this node to the process identified by .Fa pid . Specifically, calls to .Xr getdirentries 2 and .Xr getdents 2 will be routed to userland after the current actual directory contents are read into userland. .It Fa AUTO_DIRECT -Set the directory as a mount trigger. Any request to enter the directory +Set the directory as a mount trigger. +Any request to enter the directory will trigger a callback into the process .Fa pid . .It Fa AUTO_INDIRECT -Set the directory as an indirect trigger. Any request for an entry inside +Set the directory as an indirect trigger. +Any request for an entry inside the directory will be routed to the process identified by .Fa pid . .El .Sh EXAMPLES See /usr/share/examples/autofs/driver/ .Sh HISTORY The .Nm utility first appeared in .Fx 6.0 . .Sh AUTHORS This manual page and the autofs file system suite were written by .An Alfred Perlstein . Index: head/lib/libc/gen/sysctl.3 =================================================================== --- head/lib/libc/gen/sysctl.3 (revision 147401) +++ head/lib/libc/gen/sysctl.3 (revision 147402) @@ -1,873 +1,879 @@ .\" Copyright (c) 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 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. .\" .\" @(#)sysctl.3 8.4 (Berkeley) 5/9/95 .\" $FreeBSD$ .\" .Dd January 23, 2001 .Dt SYSCTL 3 .Os .Sh NAME .Nm sysctl , .Nm sysctlbyname , .Nm sysctlnametomib .Nd get or set system information .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/sysctl.h .Ft int .Fn sysctl "int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" .Ft int .Fn sysctlbyname "const char *name" "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" .Ft int .Fn sysctlnametomib "const char *name" "int *mibp" "size_t *sizep" .Sh DESCRIPTION The .Fn sysctl function retrieves system information and allows processes with appropriate privileges to set system information. The information available from .Fn sysctl consists of integers, strings, and tables. Information may be retrieved and set from the command interface using the .Xr sysctl 8 utility. .Pp Unless explicitly noted below, .Fn sysctl returns a consistent snapshot of the data requested. Consistency is obtained by locking the destination buffer into memory so that the data may be copied out without blocking. Calls to .Fn sysctl are serialized to avoid deadlock. .Pp The state is described using a ``Management Information Base'' (MIB) style name, listed in .Fa name , which is a .Fa namelen length array of integers. .Pp The .Fn sysctlbyname function accepts an ASCII representation of the name and internally looks up the integer name vector. Apart from that, it behaves the same as the standard .Fn sysctl function. .Pp The information is copied into the buffer specified by .Fa oldp . The size of the buffer is given by the location specified by .Fa oldlenp before the call, and that location gives the amount of data copied after a successful call and after a call that returns with the error code .Er ENOMEM . If the amount of data available is greater than the size of the buffer supplied, the call supplies as much data as fits in the buffer provided and returns with the error code .Er ENOMEM . If the old value is not desired, .Fa oldp and .Fa oldlenp should be set to NULL. .Pp The size of the available data can be determined by calling .Fn sysctl with the .Dv NULL argument for .Fa oldp . The size of the available data will be returned in the location pointed to by .Fa oldlenp . For some operations, the amount of space may change often. For these operations, the system attempts to round up so that the returned size is large enough for a call to return the data shortly thereafter. .Pp To set a new value, .Fa newp is set to point to a buffer of length .Fa newlen from which the requested value is to be taken. If a new value is not to be set, .Fa newp should be set to NULL and .Fa newlen set to 0. .Pp The .Fn sysctlnametomib function accepts an ASCII representation of the name, looks up the integer name vector, and returns the numeric representation in the mib array pointed to by .Fa mibp . The number of elements in the mib array is given by the location specified by .Fa sizep before the call, and that location gives the number of entries copied after a successful call. The resulting .Fa mib and .Fa size may be used in subsequent .Fn sysctl calls to get the data associated with the requested ASCII name. This interface is intended for use by applications that want to repeatedly request the same variable (the .Fn sysctl function runs in about a third the time as the same request made via the .Fn sysctlbyname function). The .Fn sysctlnametomib function is also useful for fetching mib prefixes and then adding a final component. For example, to fetch process information for processes with pid's less than 100: .Pp .Bd -literal -offset indent -compact int i, mib[4]; size_t len; struct kinfo_proc kp; /* Fill out the first three components of the mib */ len = 4; sysctlnametomib("kern.proc.pid", mib, &len); /* Fetch and print entries for pid's < 100 */ for (i = 0; i < 100; i++) { mib[3] = i; len = sizeof(kp); if (sysctl(mib, 4, &kp, &len, NULL, 0) == -1) perror("sysctl"); else if (len > 0) printkproc(&kp); } .Ed .Pp The top level names are defined with a CTL_ prefix in .In sys/sysctl.h , and are as follows. The next and subsequent levels down are found in the include files listed here, and described in separate sections below. .Pp .Bl -column CTLXMACHDEPXXX "Next level namesXXXXXX" -offset indent .It Sy "Name Next level names Description" .It "CTL_DEBUG sys/sysctl.h Debugging" .It "CTL_VFS sys/mount.h File system" .It "CTL_HW sys/sysctl.h Generic CPU, I/O" .It "CTL_KERN sys/sysctl.h High kernel limits" .It "CTL_MACHDEP sys/sysctl.h Machine dependent" .It "CTL_NET sys/socket.h Networking" .It "CTL_USER sys/sysctl.h User-level" .It "CTL_VM vm/vm_param.h Virtual memory" .El .Pp For example, the following retrieves the maximum number of processes allowed in the system: .Pp .Bd -literal -offset indent -compact int mib[2], maxproc; size_t len; mib[0] = CTL_KERN; mib[1] = KERN_MAXPROC; len = sizeof(maxproc); sysctl(mib, 2, &maxproc, &len, NULL, 0); .Ed .Pp To retrieve the standard search path for the system utilities: .Pp .Bd -literal -offset indent -compact int mib[2]; size_t len; char *p; mib[0] = CTL_USER; mib[1] = USER_CS_PATH; sysctl(mib, 2, NULL, &len, NULL, 0); p = malloc(len); sysctl(mib, 2, p, &len, NULL, 0); .Ed .Ss CTL_DEBUG The debugging variables vary from system to system. A debugging variable may be added or deleted without need to recompile .Fn sysctl to know about it. Each time it runs, .Fn sysctl gets the list of debugging variables from the kernel and displays their current values. The system defines twenty .Pq Vt "struct ctldebug" variables named .Va debug0 through .Va debug19 . They are declared as separate variables so that they can be individually initialized at the location of their associated variable. The loader prevents multiple use of the same variable by issuing errors if a variable is initialized in more than one place. For example, to export the variable .Va dospecialcheck as a debugging variable, the following declaration would be used: .Pp .Bd -literal -offset indent -compact int dospecialcheck = 1; struct ctldebug debug5 = { "dospecialcheck", &dospecialcheck }; .Ed .Ss CTL_VFS A distinguished second level name, VFS_GENERIC, is used to get general information about all file systems. One of its third level identifiers is VFS_MAXTYPENUM that gives the highest valid file system type number. Its other third level identifier is VFS_CONF that returns configuration information about the file system type given as a fourth level identifier (see .Xr getvfsbyname 3 as an example of its use). The remaining second level identifiers are the file system type number returned by a .Xr statfs 2 call or from VFS_CONF. The third level identifiers available for each file system are given in the header file that defines the mount argument structure for that file system. .Ss CTL_HW The string and integer information available for the CTL_HW level is detailed below. The changeable column shows whether a process with appropriate privilege may change the value. .Bl -column "Second level nameXXXXXX" integerXXX -offset indent .It Sy "Second level name Type Changeable" .It "HW_MACHINE string no" .It "HW_MODEL string no" .It "HW_NCPU integer no" .It "HW_BYTEORDER integer no" .It "HW_PHYSMEM integer no" .It "HW_USERMEM integer no" .It "HW_PAGESIZE integer no" .It "HW_FLOATINGPOINT integer no" .It "HW_MACHINE_ARCH string no" .\".It "HW_DISKNAMES integer no" .\".It "HW_DISKSTATS integer no" .El .Pp .Bl -tag -width 6n .It Li HW_MACHINE The machine class. .It Li HW_MODEL The machine model .It Li HW_NCPU The number of cpus. .It Li HW_BYTEORDER The byteorder (4,321, or 1,234). .It Li HW_PHYSMEM The bytes of physical memory. .It Li HW_USERMEM The bytes of non-kernel memory. .It Li HW_PAGESIZE The software page size. .It Li HW_FLOATINGPOINT Nonzero if the floating point support is in hardware. .It Li HW_MACHINE_ARCH The machine dependent architecture type. .\".It Fa HW_DISKNAMES .\".It Fa HW_DISKSTATS .El .Ss CTL_KERN The string and integer information available for the CTL_KERN level is detailed below. The changeable column shows whether a process with appropriate privilege may change the value. The types of data currently available are process information, system vnodes, the open file entries, routing table entries, virtual memory statistics, load average history, and clock rate information. .Bl -column "KERNXMAXFILESPERPROCXXX" "struct clockrateXXX" -offset indent .It Sy "Second level name Type Changeable" .It "KERN_ARGMAX integer no" .It "KERN_BOOTFILE string yes" .It "KERN_BOOTTIME struct timeval no" .It "KERN_CLOCKRATE struct clockinfo no" .It "KERN_FILE struct file no" .It "KERN_HOSTID integer yes" .It "KERN_HOSTNAME string yes" .It "KERN_JOB_CONTROL integer no" .It "KERN_MAXFILES integer yes" .It "KERN_MAXFILESPERPROC integer yes" .It "KERN_MAXPROC integer no" .It "KERN_MAXPROCPERUID integer yes" .It "KERN_MAXVNODES integer yes" .It "KERN_NGROUPS integer no" .It "KERN_NISDOMAINNAME string yes" .It "KERN_OSRELDATE integer no" .It "KERN_OSRELEASE string no" .It "KERN_OSREV integer no" .It "KERN_OSTYPE string no" .It "KERN_POSIX1 integer no" .It "KERN_PROC struct proc no" .It "KERN_PROF node not applicable" .It "KERN_QUANTUM integer yes" .It "KERN_SAVED_IDS integer no" .It "KERN_SECURELVL integer raise only" .It "KERN_UPDATEINTERVAL integer no" .It "KERN_VERSION string no" .It "KERN_VNODE struct vnode no" .El .Pp .Bl -tag -width 6n .It Li KERN_ARGMAX The maximum bytes of argument to .Xr execve 2 . .It Li KERN_BOOTFILE The full pathname of the file from which the kernel was loaded. .It Li KERN_BOOTTIME A .Va struct timeval structure is returned. This structure contains the time that the system was booted. .It Li KERN_CLOCKRATE A .Va struct clockinfo structure is returned. This structure contains the clock, statistics clock and profiling clock frequencies, the number of micro-seconds per hz tick and the skew rate. .It Li KERN_FILE Return the entire file table. The returned data consists of a single .Va struct filehead followed by an array of .Va struct file , whose size depends on the current number of such objects in the system. .It Li KERN_HOSTID Get or set the host id. .It Li KERN_HOSTNAME Get or set the hostname. .It Li KERN_JOB_CONTROL Return 1 if job control is available on this system, otherwise 0. .It Li KERN_MAXFILES The maximum number of files that may be open in the system. .It Li KERN_MAXFILESPERPROC The maximum number of files that may be open for a single process. This limit only applies to processes with an effective uid of nonzero at the time of the open request. Files that have already been opened are not affected if the limit or the effective uid is changed. .It Li KERN_MAXPROC The maximum number of concurrent processes the system will allow. .It Li KERN_MAXPROCPERUID The maximum number of concurrent processes the system will allow for a single effective uid. This limit only applies to processes with an effective uid of nonzero at the time of a fork request. Processes that have already been started are not affected if the limit is changed. .It Li KERN_MAXVNODES The maximum number of vnodes available on the system. .It Li KERN_NGROUPS The maximum number of supplemental groups. .It Li KERN_NISDOMAINNAME The name of the current YP/NIS domain. .It Li KERN_OSRELDATE The kernel release version in the format .Ar M Ns Ar mm Ns Ar R Ns Ar xx , where .Ar M is the major version, .Ar mm is the two digit minor version, .Ar R is 0 if release branch, otherwise 1, and .Ar xx is updated when the available APIs change. .Pp The userland release version is available from .In osreldate.h ; parse this file if you need to get the release version of the currently installed userland. .It Li KERN_OSRELEASE The system release string. .It Li KERN_OSREV The system revision string. .It Li KERN_OSTYPE The system type string. .It Li KERN_POSIX1 The version of .St -p1003.1 with which the system attempts to comply. .It Li KERN_PROC Return selected information about specific running processes. .Pp For the following names, an array of pairs of .Va struct proc followed by corresponding .Va struct eproc structures is returned, whose size depends on the current number of such objects in the system. .Bl -column "Third level nameXXXXXX" "Fourth level is:XXXXXX" -offset indent .It "Third level name Fourth level is:" .It "KERN_PROC_ALL None" .It "KERN_PROC_PID A process ID" .It "KERN_PROC_PGRP A process group" .It "KERN_PROC_TTY A tty device" .It "KERN_PROC_UID A user ID" .It "KERN_PROC_RUID A real user ID" .El .Pp -If the third level name is KERN_PROC_ARGS then the command line argument +If the third level name is +.Dv KERN_PROC_ARGS +then the command line argument array is returned in a flattened form, i.e., zero-terminated arguments follow each other. The total size of array is returned. It is also possible for a process to set its own process title this way. -If the third level name is KERN_PROC_PATHNAME, the path of the +If the third level name is +.Dv KERN_PROC_PATHNAME , +the path of the process' text file is stored. -For KERN_PROC_PATHNAME, a process ID of -.Li -1 +For +.Dv KERN_PROC_PATHNAME , +a process ID of +.Li \-1 implies the current process. .Bl -column "Third level nameXXXXXX" "Fourth level is:XXXXXX" -offset indent .It Sy "Third level name Fourth level is:" -.It "KERN_PROC_ARGS A process ID" -.It "KERN_PROC_PATHNAME A process ID" +.It Dv KERN_PROC_ARGS Ta "A process ID" +.It Dv KERN_PROC_PATHNAME Ta "A process ID" .El .It Li KERN_PROF Return profiling information about the kernel. If the kernel is not compiled for profiling, attempts to retrieve any of the KERN_PROF values will fail with .Er ENOENT . The third level names for the string and integer profiling information is detailed below. The changeable column shows whether a process with appropriate privilege may change the value. .Bl -column "GPROFXGMONPARAMXXX" "struct gmonparamXXX" -offset indent .It Sy "Third level name Type Changeable" .It "GPROF_STATE integer yes" .It "GPROF_COUNT u_short[\|] yes" .It "GPROF_FROMS u_short[\|] yes" .It "GPROF_TOS struct tostruct yes" .It "GPROF_GMONPARAM struct gmonparam no" .El .Pp The variables are as follows: .Bl -tag -width 6n .It Li GPROF_STATE Returns GMON_PROF_ON or GMON_PROF_OFF to show that profiling is running or stopped. .It Li GPROF_COUNT Array of statistical program counter counts. .It Li GPROF_FROMS Array indexed by program counter of call-from points. .It Li GPROF_TOS Array of .Va struct tostruct describing destination of calls and their counts. .It Li GPROF_GMONPARAM Structure giving the sizes of the above arrays. .El .It Li KERN_QUANTUM The maximum period of time, in microseconds, for which a process is allowed to run without being preempted if other processes are in the run queue. .It Li KERN_SAVED_IDS Returns 1 if saved set-group and saved set-user ID is available. .It Li KERN_SECURELVL The system security level. This level may be raised by processes with appropriate privilege. It may not be lowered. .It Li KERN_VERSION The system version string. .It Li KERN_VNODE Return the entire vnode table. Note, the vnode table is not necessarily a consistent snapshot of the system. The returned data consists of an array whose size depends on the current number of such objects in the system. Each element of the array contains the kernel address of a vnode .Va struct vnode * followed by the vnode itself .Va struct vnode . .El .Ss CTL_MACHDEP The set of variables defined is architecture dependent. The following variables are defined for the i386 architecture. .Bl -column "CONSOLE_DEVICEXXX" "struct bootinfoXXX" -offset indent .It Sy "Second level name Type Changeable" .It Li "CPU_CONSDEV dev_t no" .It Li "CPU_ADJKERNTZ int yes" .It Li "CPU_DISRTCSET int yes" .It Li "CPU_BOOTINFO struct bootinfo no" .It Li "CPU_WALLCLOCK int yes" .El .Ss CTL_NET The string and integer information available for the CTL_NET level is detailed below. The changeable column shows whether a process with appropriate privilege may change the value. .Bl -column "Second level nameXXXXXX" "routing messagesXXX" -offset indent .It Sy "Second level name Type Changeable" .It "PF_ROUTE routing messages no" .It "PF_INET IPv4 values yes" .It "PF_INET6 IPv6 values yes" .El .Pp .Bl -tag -width 6n .It Li PF_ROUTE Return the entire routing table or a subset of it. The data is returned as a sequence of routing messages (see .Xr route 4 for the header file, format and meaning). The length of each message is contained in the message header. .Pp The third level name is a protocol number, which is currently always 0. The fourth level name is an address family, which may be set to 0 to select all address families. The fifth and sixth level names are as follows: .Bl -column "Fifth level nameXXXXXX" "Sixth level is:XXX" -offset indent .It Sy "Fifth level name Sixth level is:" .It "NET_RT_FLAGS rtflags" .It "NET_RT_DUMP None" .It "NET_RT_IFLIST 0 or if_index" .It "NET_RT_IFMALIST 0 or if_index" .El .Pp The .Dv NET_RT_IFMALIST name returns information about multicast group memberships on all interfaces if 0 is specified, or for the interface specified by .Va if_index . .It Li PF_INET Get or set various global information about the IPv4 (Internet Protocol version 4). The third level name is the protocol. The fourth level name is the variable name. The currently defined protocols and names are: .Bl -column ProtocolXX VariableXX TypeXX ChangeableXX .It Sy "Protocol Variable Type Changeable" .It "icmp bmcastecho integer yes" .It "icmp maskrepl integer yes" .It "ip forwarding integer yes" .It "ip redirect integer yes" .It "ip ttl integer yes" .It "udp checksum integer yes" .El .Pp The variables are as follows: .Bl -tag -width 6n .It Li icmp.bmcastecho Returns 1 if an ICMP echo request to a broadcast or multicast address is to be answered. .It Li icmp.maskrepl Returns 1 if ICMP network mask requests are to be answered. .It Li ip.forwarding Returns 1 when IP forwarding is enabled for the host, meaning that the host is acting as a router. .It Li ip.redirect Returns 1 when ICMP redirects may be sent by the host. This option is ignored unless the host is routing IP packets, and should normally be enabled on all systems. .It Li ip.ttl The maximum time-to-live (hop count) value for an IP packet sourced by the system. This value applies to normal transport protocols, not to ICMP. .It Li udp.checksum Returns 1 when UDP checksums are being computed and checked. Disabling UDP checksums is strongly discouraged. .Pp For variables net.inet.*.ipsec, please refer to .Xr ipsec 4 . .El .It Li PF_INET6 Get or set various global information about the IPv6 (Internet Protocol version 6). The third level name is the protocol. The fourth level name is the variable name. .Pp For variables net.inet6.* please refer to .Xr inet6 4 . For variables net.inet6.*.ipsec6, please refer to .Xr ipsec 4 . .El .Ss CTL_USER The string and integer information available for the CTL_USER level is detailed below. The changeable column shows whether a process with appropriate privilege may change the value. .Bl -column "USER_COLL_WEIGHTS_MAXXXX" "integerXXX" -offset indent .It Sy "Second level name Type Changeable" .It "USER_BC_BASE_MAX integer no" .It "USER_BC_DIM_MAX integer no" .It "USER_BC_SCALE_MAX integer no" .It "USER_BC_STRING_MAX integer no" .It "USER_COLL_WEIGHTS_MAX integer no" .It "USER_CS_PATH string no" .It "USER_EXPR_NEST_MAX integer no" .It "USER_LINE_MAX integer no" .It "USER_POSIX2_CHAR_TERM integer no" .It "USER_POSIX2_C_BIND integer no" .It "USER_POSIX2_C_DEV integer no" .It "USER_POSIX2_FORT_DEV integer no" .It "USER_POSIX2_FORT_RUN integer no" .It "USER_POSIX2_LOCALEDEF integer no" .It "USER_POSIX2_SW_DEV integer no" .It "USER_POSIX2_UPE integer no" .It "USER_POSIX2_VERSION integer no" .It "USER_RE_DUP_MAX integer no" .It "USER_STREAM_MAX integer no" .It "USER_TZNAME_MAX integer no" .El .Bl -tag -width 6n .Pp .It Li USER_BC_BASE_MAX The maximum ibase/obase values in the .Xr bc 1 utility. .It Li USER_BC_DIM_MAX The maximum array size in the .Xr bc 1 utility. .It Li USER_BC_SCALE_MAX The maximum scale value in the .Xr bc 1 utility. .It Li USER_BC_STRING_MAX The maximum string length in the .Xr bc 1 utility. .It Li USER_COLL_WEIGHTS_MAX The maximum number of weights that can be assigned to any entry of the LC_COLLATE order keyword in the locale definition file. .It Li USER_CS_PATH Return a value for the .Ev PATH environment variable that finds all the standard utilities. .It Li USER_EXPR_NEST_MAX The maximum number of expressions that can be nested within parenthesis by the .Xr expr 1 utility. .It Li USER_LINE_MAX The maximum length in bytes of a text-processing utility's input line. .It Li USER_POSIX2_CHAR_TERM Return 1 if the system supports at least one terminal type capable of all operations described in .St -p1003.2 , otherwise 0. .It Li USER_POSIX2_C_BIND Return 1 if the system's C-language development facilities support the C-Language Bindings Option, otherwise 0. .It Li USER_POSIX2_C_DEV Return 1 if the system supports the C-Language Development Utilities Option, otherwise 0. .It Li USER_POSIX2_FORT_DEV Return 1 if the system supports the FORTRAN Development Utilities Option, otherwise 0. .It Li USER_POSIX2_FORT_RUN Return 1 if the system supports the FORTRAN Runtime Utilities Option, otherwise 0. .It Li USER_POSIX2_LOCALEDEF Return 1 if the system supports the creation of locales, otherwise 0. .It Li USER_POSIX2_SW_DEV Return 1 if the system supports the Software Development Utilities Option, otherwise 0. .It Li USER_POSIX2_UPE Return 1 if the system supports the User Portability Utilities Option, otherwise 0. .It Li USER_POSIX2_VERSION The version of .St -p1003.2 with which the system attempts to comply. .It Li USER_RE_DUP_MAX The maximum number of repeated occurrences of a regular expression permitted when using interval notation. .It Li USER_STREAM_MAX The minimum maximum number of streams that a process may have open at any one time. .It Li USER_TZNAME_MAX The minimum maximum number of types supported for the name of a timezone. .El .Ss CTL_VM The string and integer information available for the CTL_VM level is detailed below. The changeable column shows whether a process with appropriate privilege may change the value. .Bl -column "Second level nameXXXXXX" "struct loadavgXXX" -offset indent .It Sy "Second level name Type Changeable" .It "VM_LOADAVG struct loadavg no" .It "VM_METER struct vmtotal no" .It "VM_PAGEOUT_ALGORITHM integer yes" .It "VM_SWAPPING_ENABLED integer maybe" .It "VM_V_CACHE_MAX integer yes" .It "VM_V_CACHE_MIN integer yes" .It "VM_V_FREE_MIN integer yes" .It "VM_V_FREE_RESERVED integer yes" .It "VM_V_FREE_TARGET integer yes" .It "VM_V_INACTIVE_TARGET integer yes" .It "VM_V_PAGEOUT_FREE_MIN integer yes" .El .Pp .Bl -tag -width 6n .It Li VM_LOADAVG Return the load average history. The returned data consists of a .Va struct loadavg . .It Li VM_METER Return the system wide virtual memory statistics. The returned data consists of a .Va struct vmtotal . .It Li VM_PAGEOUT_ALGORITHM 0 if the statistics-based page management algorithm is in use or 1 if the near-LRU algorithm is in use. .It Li VM_SWAPPING_ENABLED 1 if process swapping is enabled or 0 if disabled. This variable is permanently set to 0 if the kernel was built with swapping disabled. .It Li VM_V_CACHE_MAX Maximum desired size of the cache queue. .It Li VM_V_CACHE_MIN Minimum desired size of the cache queue. If the cache queue size falls very far below this value, the pageout daemon is awakened. .It Li VM_V_FREE_MIN Minimum amount of memory (cache memory plus free memory) required to be available before a process waiting on memory will be awakened. .It Li VM_V_FREE_RESERVED Processes will awaken the pageout daemon and wait for memory if the number of free and cached pages drops below this value. .It Li VM_V_FREE_TARGET The total amount of free memory (including cache memory) that the pageout daemon tries to maintain. .It Li VM_V_INACTIVE_TARGET The desired number of inactive pages that the pageout daemon should achieve when it runs. Inactive pages can be quickly inserted into process address space when needed. .It Li VM_V_PAGEOUT_FREE_MIN If the amount of free and cache memory falls below this value, the pageout daemon will enter "memory conserving mode" to avoid deadlock. .El .Sh RETURN VALUES .Rv -std .Sh FILES .Bl -tag -width -compact .It In sys/sysctl.h definitions for top level identifiers, second level kernel and hardware identifiers, and user level identifiers .It In sys/socket.h definitions for second level network identifiers .It In sys/gmon.h definitions for third level profiling identifiers .It In vm/vm_param.h definitions for second level virtual memory identifiers .It In netinet/in.h definitions for third level IPv4/IPv6 identifiers and fourth level IPv4/v6 identifiers .It In netinet/icmp_var.h definitions for fourth level ICMP identifiers .It In netinet/icmp6.h definitions for fourth level ICMPv6 identifiers .It In netinet/udp_var.h definitions for fourth level UDP identifiers .El .Sh ERRORS The following errors may be reported: .Bl -tag -width Er .It Bq Er EFAULT The buffer .Fa name , .Fa oldp , .Fa newp , or length pointer .Fa oldlenp contains an invalid address. .It Bq Er EINVAL The .Fa name array is less than two or greater than CTL_MAXNAME. .It Bq Er EINVAL A non-null .Fa newp is given and its specified length in .Fa newlen is too large or too small. .It Bq Er ENOMEM The length pointed to by .Fa oldlenp is too short to hold the requested value. .It Bq Er ENOMEM The smaller of either the length pointed to by .Fa oldlenp or the estimated size of the returned data exceeds the system limit on locked memory. .It Bq Er ENOMEM Locking the buffer .Fa oldp , or a portion of the buffer if the estimated size of the data to be returned is smaller, would cause the process to exceed its per-process locked memory limit. .It Bq Er ENOTDIR The .Fa name array specifies an intermediate rather than terminal name. .It Bq Er EISDIR The .Fa name array specifies a terminal name, but the actual name is not terminal. .It Bq Er ENOENT The .Fa name array specifies a value that is unknown. .It Bq Er EPERM An attempt is made to set a read-only value. .It Bq Er EPERM A process without appropriate privilege attempts to set a value. .El .Sh SEE ALSO .Xr sysconf 3 , .Xr sysctl 8 .Sh HISTORY The .Fn sysctl function first appeared in .Bx 4.4 . Index: head/lib/libc/gen/ttyname.3 =================================================================== --- head/lib/libc/gen/ttyname.3 (revision 147401) +++ head/lib/libc/gen/ttyname.3 (revision 147402) @@ -1,148 +1,161 @@ .\" Copyright (c) 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 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. .\" .\" @(#)ttyname.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd May 14, 2005 .Dt TTYNAME 3 .Os .Sh NAME .Nm ttyname , .Nm ttyname_r , .Nm isatty , .Nm ttyslot .Nd get name of associated terminal (tty) from file descriptor .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft char * .Fn ttyname "int fd" .Ft int .Fn ttyname_r "int fd" "char *buf" "size_t len" .Ft int .Fn isatty "int fd" .Ft int .Fn ttyslot void .Sh DESCRIPTION These functions operate on the system file descriptors for terminal type devices. These descriptors are not related to the standard .Tn I/O .Dv FILE typedef, but refer to the special device files found in .Pa /dev and named .Pa /dev/tty Ns Ar xx and for which an entry exists in the initialization file .Pa /etc/ttys . (See .Xr ttys 5 . ) .Pp The .Fn isatty function determines if the file descriptor .Fa fd refers to a valid terminal type device. .Pp The .Fn ttyname function gets the related device name of a file descriptor for which .Fn isatty is true. .Pp +The .Fn ttyname +function returns the name stored in a static buffer which will be overwritten on subsequent calls. +The .Fn ttyname_r +function takes a buffer and length as arguments to avoid this problem. .Pp The .Fn ttyslot function fetches the current process' control terminal number from the .Xr ttys 5 file entry. .Sh RETURN VALUES The .Fn ttyname function returns the null terminated name if the device is found and .Fn isatty is true; otherwise a .Dv NULL pointer is returned. The .Fn ttyname_r -function returns 0 if successful. Otherwise an error number is returned. +function returns 0 if successful. +Otherwise an error number is returned. .Pp The .Fn ttyslot function returns the unit number of the device file if found; otherwise the value zero is returned. +.Sh FILES +.Bl -tag -width ".Pa /etc/ttys" -compact +.It Pa /dev/\(** +.It Pa /etc/ttys +.El .Sh ERRORS +The .Fn ttyname_r -may return the following error codes: +may fail and return the following error codes: .Bl -tag -width Er .It Bq Er ENOTTY +The .Fa fd +argument is not a valid file descriptor. .It Bq Er ERANGE +The .Fa bufsize +argument is smaller than the length of the string to be returned. -.Sh FILES -.Bl -tag -width /etc/ttys -compact -.It Pa /dev/\(** -.It Pa /etc/ttys .El .Sh SEE ALSO .Xr ioctl 2 , .Xr ttys 5 .Sh HISTORY -A +The .Fn isatty , .Fn ttyname , and .Fn ttyslot -function +functions appeared in .At v7 . +The .Fn ttyname_r +function appeared in .Fx 6.0 . Index: head/lib/libc/net/getaddrinfo.3 =================================================================== --- head/lib/libc/net/getaddrinfo.3 (revision 147401) +++ head/lib/libc/net/getaddrinfo.3 (revision 147402) @@ -1,432 +1,434 @@ .\" $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 December 20, 2004 .Dt GETADDRINFO 3 .Os .Sh NAME .Nm getaddrinfo , .Nm freeaddrinfo .Nd socket address structure to host and service name .Sh SYNOPSIS .Fd #include .Fd #include .Fd #include .Ft int -.Fn getaddrinfo "const char *hostname" "const char *servname" \ - "const struct addrinfo *hints" "struct addrinfo **res" +.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 .Fa ai_flags is formed by .Tn OR Ns 'ing the following values: .Bl -tag -width "AI_CANONNAMEXX" .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_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, 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 draft-ietf-ipv6-scoping-arch-02.txt. 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 internet draft .%N draft-ietf-ipv6-scoping-arch-02.txt .%O work in progress material .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.1g-2000 draft specification and documented in .Dv "RFC 3493" , .Dq Basic Socket Interface Extensions for IPv6 . Index: head/lib/libc/net/getnameinfo.3 =================================================================== --- head/lib/libc/net/getnameinfo.3 (revision 147401) +++ head/lib/libc/net/getnameinfo.3 (revision 147402) @@ -1,268 +1,270 @@ .\" $KAME: getnameinfo.3,v 1.37 2005/01/05 03:23:05 itojun Exp $ .\" $OpenBSD: getnameinfo.3,v 1.36 2004/12/21 09:48:20 jmc 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 December 20, 2004 .Dt GETNAMEINFO 3 .Os .Sh NAME .Nm getnameinfo .Nd socket address structure to hostname and service name .Sh SYNOPSIS .Fd #include .Fd #include .Fd #include .Ft int -.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" "char *host" \ - "size_t hostlen" "char *serv" "size_t servlen" "int flags" +.Fo getnameinfo +.Fa "const struct sockaddr *sa" "socklen_t salen" "char *host" +.Fa "size_t hostlen" "char *serv" "size_t servlen" "int flags" +.Fc .Sh DESCRIPTION The .Fn getnameinfo function is used to convert a .Li sockaddr structure to a pair of host name and service strings. It is a replacement for and provides more flexibility than the .Xr gethostbyaddr 3 and .Xr getservbyport 3 functions and is the converse of the .Xr getaddrinfo 3 function. .Pp The .Li sockaddr structure .Fa sa should point to either a .Li sockaddr_in or .Li sockaddr_in6 structure (for IPv4 or IPv6 respectively) that is .Fa salen bytes long. .Pp The host and service names associated with .Fa sa are stored in .Fa host and .Fa serv which have length parameters .Fa hostlen and .Fa servlen . The maximum value for .Fa hostlen is .Dv NI_MAXHOST and the maximum value for .Fa servlen is .Dv NI_MAXSERV , as defined by .Aq Pa netdb.h . If a length parameter is zero, no string will be stored. Otherwise, enough space must be provided to store the host name or service string plus a byte for the NUL terminator. .Pp The .Fa flags argument is formed by .Tn OR Ns 'ing the following values: .Bl -tag -width "NI_NUMERICHOSTXX" .It Dv NI_NOFQDN A fully qualified domain name is not required for local hosts. The local part of the fully qualified domain name is returned instead. .It Dv NI_NUMERICHOST Return the address in numeric form, as if calling .Xr inet_ntop 3 , instead of a host name. .It Dv NI_NAMEREQD A name is required. If the host name cannot be found in DNS and this flag is set, a non-zero error code is returned. If the host name is not found and the flag is not set, the address is returned in numeric form. .It NI_NUMERICSERV The service name is returned as a digit string representing the port number. .It NI_DGRAM Specifies that the service being looked up is a datagram service, and causes .Xr getservbyport 3 to be called with a second argument of .Dq udp instead of its default of .Dq tcp . This is required for the few ports (512\-514) that have different services for .Tn UDP and .Tn TCP . .El .Pp This implementation allows numeric IPv6 address notation with scope identifier, as documented in chapter 11 of draft-ietf-ipv6-scoping-arch-02.txt. IPv6 link-local address will appear as a string like .Dq Li fe80::1%ne0 . Refer to .Xr getaddrinfo 3 for more information. .Sh RETURN VALUES .Fn getnameinfo 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 get a numeric host name, and service name, for a given socket address. Observe that there is no hardcoded reference to a particular address family. .Bd -literal -offset indent struct sockaddr *sa; /* input */ char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV]; if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf, sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV)) { errx(1, "could not get numeric hostname"); /*NOTREACHED*/ } printf("host=%s, serv=%s\en", hbuf, sbuf); .Ed .Pp The following version checks if the socket address has a reverse address mapping: .Bd -literal -offset indent struct sockaddr *sa; /* input */ char hbuf[NI_MAXHOST]; if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), NULL, 0, NI_NAMEREQD)) { errx(1, "could not resolve hostname"); /*NOTREACHED*/ } printf("host=%s\en", hbuf); .Ed .Sh SEE ALSO .Xr gai_strerror 3 , .Xr getaddrinfo 3 , .Xr gethostbyaddr 3 , .Xr getservbyport 3 , .Xr inet_ntop 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 W. Stevens .%T Basic Socket Interface Extensions for IPv6 .%R RFC 2553 .%D March 1999 .Re .Rs .%A S. Deering .%A B. Haberman .%A T. Jinmei .%A E. Nordmark .%A B. Zill .%T "IPv6 Scoped Address Architecture" .%R internet draft .%N draft-ietf-ipv6-scoping-arch-02.txt .%O work in progress material .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 getnameinfo function is defined by the .St -p1003.1g-2000 draft specification and documented in .Tn "RFC 2553" , .Dq Basic Socket Interface Extensions for IPv6 . .Sh CAVEATS .Fn getnameinfo can return both numeric and FQDN forms of the address specified in .Fa sa . There is no return value that indicates whether the string returned in .Fa host is a result of binary to numeric-text translation (like .Xr inet_ntop 3 ) , or is the result of a DNS reverse lookup. Because of this, malicious parties could set up a PTR record as follows: .Bd -literal -offset indent 1.0.0.127.in-addr.arpa. IN PTR 10.1.1.1 .Ed .Pp and trick the caller of .Fn getnameinfo into believing that .Fa sa is .Li 10.1.1.1 when it is actually .Li 127.0.0.1 . .Pp To prevent such attacks, the use of .Dv NI_NAMEREQD is recommended when the result of .Fn getnameinfo is used for access control purposes: .Bd -literal -offset indent struct sockaddr *sa; socklen_t salen; char addr[NI_MAXHOST]; struct addrinfo hints, *res; int error; error = getnameinfo(sa, salen, addr, sizeof(addr), NULL, 0, NI_NAMEREQD); if (error == 0) { memset(&hints, 0, sizeof(hints)); hints.ai_socktype = SOCK_DGRAM; /*dummy*/ hints.ai_flags = AI_NUMERICHOST; if (getaddrinfo(addr, "0", &hints, &res) == 0) { /* malicious PTR record */ freeaddrinfo(res); printf("bogus PTR record\en"); return -1; } /* addr is FQDN as a result of PTR lookup */ } else { /* addr is numeric string */ error = getnameinfo(sa, salen, addr, sizeof(addr), NULL, 0, NI_NUMERICHOST); } .Ed .\".Pp .\".Ox .\"intentionally uses a different .\".Dv NI_MAXHOST .\"value from what .\".Tn "RFC 2553" .\"suggests, to avoid buffer length handling mistakes. Index: head/lib/libc/net/getnetent.3 =================================================================== --- head/lib/libc/net/getnetent.3 (revision 147401) +++ head/lib/libc/net/getnetent.3 (revision 147402) @@ -1,176 +1,176 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 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. .\" .\" @(#)getnetent.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd June 4, 1993 .Dt GETNETENT 3 .Os .Sh NAME .Nm getnetent , .Nm getnetbyaddr , .Nm getnetbyname , .Nm setnetent , .Nm endnetent .Nd get network entry .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In netdb.h .Ft struct netent * .Fn getnetent void .Ft struct netent * .Fn getnetbyname "const char *name" .Ft struct netent * .Fn getnetbyaddr "uint32_t net" "int type" .Ft void .Fn setnetent "int stayopen" .Ft void .Fn endnetent void .Sh DESCRIPTION The .Fn getnetent , .Fn getnetbyname , and .Fn getnetbyaddr functions each return a pointer to an object with the following structure describing an internet network. This structure contains either the information obtained from the nameserver, .Xr named 8 , broken-out fields of a line in the network data base .Pa /etc/networks , or entries supplied by the .Xr yp 8 system. The order of the lookups is controlled by the `networks' entry in .Xr nsswitch.conf 5 . .Pp .Bd -literal -offset indent struct netent { char *n_name; /* official name of net */ char **n_aliases; /* alias list */ int n_addrtype; /* net number type */ uint32_t n_net; /* net number */ }; .Ed .Pp The members of this structure are: .Bl -tag -width n_addrtype .It Fa n_name The official name of the network. .It Fa n_aliases A zero terminated list of alternate names for the network. .It Fa n_addrtype The type of the network number returned; currently only AF_INET. .It Fa n_net The network number. Network numbers are returned in machine byte order. .El .Pp The .Fn getnetent function reads the next line of the file, opening the file if necessary. .Pp The .Fn setnetent function opens and rewinds the file. If the .Fa stayopen flag is non-zero, the net data base will not be closed after each call to .Fn getnetbyname or .Fn getnetbyaddr . .Pp The .Fn endnetent function closes the file. .Pp The .Fn getnetbyname function and .Fn getnetbyaddr sequentially search from the beginning of the file until a matching net name or net address and type is found, or until .Dv EOF is encountered. The .Fa type argument must be .Dv AF_INET . Network numbers are supplied in host order. .Sh FILES .Bl -tag -width /etc/nsswitch.conf -compact .It Pa /etc/networks .It Pa /etc/nsswitch.conf .It Pa /etc/resolv.conf .El .Sh DIAGNOSTICS Null pointer (0) returned on .Dv EOF or error. .Sh SEE ALSO .Xr networks 5 .Pp .%T RFC 1101 .Sh HISTORY The .Fn getnetent , .Fn getnetbyaddr , .Fn getnetbyname , .Fn setnetent , and .Fn endnetent functions appeared in .Bx 4.2 . .Sh BUGS The data space used by -these functions is a thread-specific; if future use requires the data, it should be +these functions is thread-specific; if future use requires the data, it should be copied before any subsequent calls to these functions overwrite it. Only Internet network numbers are currently understood. Expecting network numbers to fit in no more than 32 bits is probably naive. Index: head/lib/libc/net/inet6_rth_space.3 =================================================================== --- head/lib/libc/net/inet6_rth_space.3 (revision 147401) +++ head/lib/libc/net/inet6_rth_space.3 (revision 147402) @@ -1,224 +1,224 @@ .\" $KAME: inet6_rth_space.3,v 1.7 2005/01/05 03:00:44 itojun Exp $ .\" .\" Copyright (C) 2004 WIDE Project. .\" 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 project 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 PROJECT 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 PROJECT 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 24, 2004 .Dt INET6_RTH_SPACE 3 .Os .\" .Sh NAME .Nm inet6_rth_space , .Nm inet6_rth_init , .Nm inet6_rth_add , .Nm inet6_rth_reverse , .Nm inet6_rth_segments , .Nm inet6_rth_getaddr .Nd IPv6 Routing Header Options manipulation .\" .Sh SYNOPSIS .In netinet/in.h .Ft socklen_t .Fn inet6_rth_space "int" "int" .Ft "void *" .Fn inet6_rth_init "void *" "socklen_t" "int" "int" .Ft int .Fn inet6_rth_add "void *" "const struct in6_addr *" .Ft int .Fn inet6_rth_reverse "const void *" "void *" .Ft int .Fn inet6_rth_segments "const void *" .Ft "struct in6_addr *" .Fn inet6_rth_getaddr "const void *" "int" .\" .Sh DESCRIPTION The IPv6 Advanced API, RFC 3542, defines the functions that an application calls to build and examine IPv6 Routing headers. Routing headers are used to perform source routing in IPv6 networks. -The RFC uses the word +The RFC uses the word .Dq segments to describe addresses and that is the term used here as well. All of the functions are defined in the .In netinet/in.h header file. The functions described in this manual page all operate on routing header structures which are defined in .In netinet/ip6.h but which should not need to be modified outside the use of this API. The size and shape of the route header structures may change, so using the APIs is a more portable, long term, solution. .Pp The functions in the API are split into two groups, those that build a routing header and those that parse a received routing header. We will describe the builder functions followed by the parser functions. .Ss inet6_rth_space The .Fn inet6_rth_space function returns the number of bytes required to hold a Routing Header of the type, specified in the -.Fa type +.Fa type argument and containing the number of addresses specified in the .Fa segments argumment. -When the type is +When the type is .Dv IPV6_RTHDR_TYPE_0 the number of segments must be from 0 through 127. -Routing headers of type +Routing headers of type .Dv IPV6_RTHDR_TYPE_2 contain only one segment, and are only used with Mobile IPv6. The return value from this function is the number of bytes required to store the routing header. If the value 0 is returned then either the route header type was not recognized or another error occurred. .Ss inet6_rth_init The .Fn inet6_rth_init function initializes the pre-allocated buffer pointed to by .Fa bp to contain a routing header of the specified type The .Fa bp_len argument is used to verify that the buffer is large enough. The caller must allocate the buffer pointed to by bp. The necessary buffer size should be determined by calling .Fn inet6_rth_space described in the previous sections. .Pp The .Fn inet6_rth_init function returns a pointer to .Fa bp on success and .Dv NULL when there is an error. .Ss inet6_rth_add The .Fn inet6_rth_add function adds the IPv6 address pointed to by .Fa addr to the end of the routing header being constructed. .Pp A successful addition results in the function returning 0, otherwise \-1 is returned. .Ss inet6_rth_reverse The .Fn inet6_rth_reverse function takes a routing header, pointed to by the argument .Fa in , and writes a new routing header into the argument pointed to by .Fa out . The routing header at that sends datagrams along the reverse of that route. Both arguments are allowed to point to the same buffer meaning that the reversal can occur in place. .Pp The return value of the function is 0 on success, or \-1 when there is an error. .\" .Pp The next set of functions operate on a routing header that the application wants to parse. In the usual case such a routing header is received from the network, although these functions can also be used with routing headers that the application itself created. .Ss inet6_rth_segments The .Fn inet6_rth_segments function returns the number of segments contained in the routing header pointed to by .Fa bp . The return value is the number of segments contained in the routing header, or \-1 if an error occurred. It is not an error for 0 to be returned as a routing header may contain 0 segments. .\" .Ss inet6_rth_getaddr The .Fn inet6_rth_getaddr function is used to retrieve a single address from a routing header. The .Fa index is the location in the routing header from which the application wants to retrieve an address. -The -.Fa index +The +.Fa index parameter must have a value between 0 and one less than the number of segments present in the routing header. The -.Fn inet6_rth_segments +.Fn inet6_rth_segments function, described in the last section, should be used to determine the total number of segments in the routing header. The .Fn inet6_rth_getaddr -function returns a pointer to an IPv6 address on success or +function returns a pointer to an IPv6 address on success or .Dv NULL when an error has occurred. .\" +.Sh EXAMPLES +RFC 3542 gives extensive examples in Section 21, Appendix B. +.Pp +KAME also provides examples in the advapitest directory of its kit. +.\" .Sh DIAGNOSTICS The .Fn inet6_rth_space and .Fn inet6_rth_getaddr functions return 0 on errors. .Pp The .Fn inet6_rthdr_init function returns .Dv NULL on error. The .Fn inet6_rth_add and .Fn inet6_rth_reverse functions return 0 on success, or \-1 upon an error. -.\" -.Sh EXAMPLES -RFC 3542 gives extensive examples in Section 21, Appendix B. -.Pp -KAME also provides examples in the advapitest directory of its kit. .\" .Sh SEE ALSO .Rs .%A W. Stevens .%A M. Thomas .%A E. Nordmark .%A T. Jinmei .%T "Advanced Sockets API for IPv6" .%N RFC 3542 .%D May 2003 .Re .Rs .%A S. Deering .%A R. Hinden .%T "Internet Protocol, Version 6 (IPv6) Specification" .%N RFC2460 .%D December 1998 .Re .Sh HISTORY The implementation first appeared in KAME advanced networking kit. Index: head/lib/libc/nls/catgets.3 =================================================================== --- head/lib/libc/nls/catgets.3 (revision 147401) +++ head/lib/libc/nls/catgets.3 (revision 147402) @@ -1,82 +1,82 @@ .\" Copyright (c) 1994 Winning Strategies, 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. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by Winning Strategies, Inc. .\" 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. .\" .\" $FreeBSD$ .Dd February 12, 2005 .Dt CATGETS 3 .Os .Sh NAME .Nm catgets .Nd retrieve string from message catalog .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In nl_types.h .Ft char * .Fn catgets "nl_catd catd" "int set_id" "int msg_id" "const char *s" .Sh DESCRIPTION The .Fn catgets function attempts to retrieve message .Fa msg_id of set .Fa set_id from the message catalog referenced by the descriptor .Fa catd . The argument .Fa s points to a default message which is returned if the function is unable to retrieve the specified message. .Sh RETURN VALUES If the specified message was retrieved successfully, .Fn catgets returns a pointer to an internal buffer containing the message string; otherwise it returns .Fa s . .Sh ERRORS .Bl -tag -width Er .It Bq Er EBADF The .Fa catd -argument is not valid message catalog descriptor. +argument is not a valid message catalog descriptor. .It Bq Er EBADMSG The message identified by .Fa set_id and .Fa msg_id is not in the message catalog. .El .Sh SEE ALSO .Xr gencat 1 , .Xr catclose 3 , .Xr catopen 3 .Sh STANDARDS The .Fn catgets function conforms to .St -p1003.1-2001 . Index: head/lib/libc/sys/send.2 =================================================================== --- head/lib/libc/sys/send.2 (revision 147401) +++ head/lib/libc/sys/send.2 (revision 147402) @@ -1,238 +1,240 @@ .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 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. .\" .\" From: @(#)send.2 8.2 (Berkeley) 2/21/94 .\" $FreeBSD$ .\" .Dd February 15, 1995 .Dt SEND 2 .Os .Sh NAME .Nm send , .Nm sendto , .Nm sendmsg .Nd send a message from a socket .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In sys/types.h .In sys/socket.h .Ft ssize_t .Fn send "int s" "const void *msg" "size_t len" "int flags" .Ft ssize_t .Fn sendto "int s" "const void *msg" "size_t len" "int flags" "const struct sockaddr *to" "socklen_t tolen" .Ft ssize_t .Fn sendmsg "int s" "const struct msghdr *msg" "int flags" .Sh DESCRIPTION The .Fn send function, and .Fn sendto and .Fn sendmsg system calls are used to transmit a message to another socket. The .Fn send function may be used only when the socket is in a .Em connected state, while .Fn sendto and .Fn sendmsg may be used at any time. .Pp The address of the target is given by .Fa to with .Fa tolen specifying its size. The length of the message is given by .Fa len . If the message is too long to pass atomically through the underlying protocol, the error .Er EMSGSIZE is returned, and the message is not transmitted. .Pp No indication of failure to deliver is implicit in a .Fn send . Locally detected errors are indicated by a return value of -1. .Pp If no messages space is available at the socket to hold the message to be transmitted, then .Fn 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. .Pp The .Fa flags argument may include one or more of the following: .Bd -literal #define MSG_OOB 0x00001 /* process out-of-band data */ #define MSG_PEEK 0x00002 /* peek at incoming message */ #define MSG_DONTROUTE 0x00004 /* bypass routing, use direct interface */ #define MSG_EOR 0x00008 /* data completes record */ #define MSG_EOF 0x00100 /* data completes transaction */ #define MSG_NOSIGNAL 0x20000 /* do not generate SIGPIPE on EOF */ .Ed .Pp The flag .Dv MSG_OOB is used to send .Dq out-of-band data on sockets that support this notion (e.g.\& .Dv SOCK_STREAM ) ; the underlying protocol must also support .Dq out-of-band data. .Dv MSG_EOR is used to indicate a record mark for protocols which support the concept. .Dv MSG_EOF requests that the sender side of a socket be shut down, and that an appropriate indication be sent at the end of the specified data; this flag is only implemented for .Dv SOCK_STREAM sockets in the .Dv PF_INET protocol family, and is used to implement Transaction .Tn TCP (see .Xr ttcp 4 ) . .Dv MSG_DONTROUTE is usually used only by diagnostic or routing programs. .Dv MSG_NOSIGNAL -is used to prevent SIGPIPE generation when writing a socket that +is used to prevent +.Dv SIGPIPE +generation when writing a socket that may be closed. .Pp See .Xr recv 2 for a description of the .Fa msghdr structure. .Sh RETURN VALUES The call returns the number of characters sent, or -1 if an error occurred. .Sh ERRORS The .Fn send function and .Fn sendto and .Fn sendmsg system calls fail if: .Bl -tag -width Er .It Bq Er EBADF An invalid descriptor was specified. .It Bq Er EACCES The destination address is a broadcast address, and .Dv SO_BROADCAST has not been set on the socket. .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 EISCONN A destination address was specified and the socket is already connected. .It Bq Er ECONNREFUSED The socket received an ICMP destination unreachable message from the last message sent. This typically means that the receiver is not listening on the remote port. .It Bq Er EHOSTDOWN The remote host was down. .It Bq Er ENETDOWN The remote network was down. .It Bq Er EPERM The process using a .Dv SOCK_RAW socket was jailed and the source address specified in the IP header did not match the IP address bound to the prison. .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. .El .Sh SEE ALSO .Xr fcntl 2 , .Xr getsockopt 2 , .Xr recv 2 , .Xr select 2 , .Xr socket 2 , .Xr write 2 .Sh HISTORY The .Fn send function appeared in .Bx 4.2 . .Sh BUGS Because .Fn sendmsg does not necessarily block until the data has been transferred, it is possible to transfer an open file descriptor across an .Dv AF_UNIX domain socket (see .Xr recv 2 ) , then .Fn close it before it has actually been sent, the result being that the receiver gets a closed file descriptor. It is left to the application to implement an acknowledgment mechanism to prevent this from happening. Index: head/lib/libpam/modules/pam_exec/pam_exec.8 =================================================================== --- head/lib/libpam/modules/pam_exec/pam_exec.8 (revision 147401) +++ head/lib/libpam/modules/pam_exec/pam_exec.8 (revision 147402) @@ -1,75 +1,75 @@ .\" Copyright (c) 2001,2003 Networks Associates Technology, Inc. .\" All rights reserved. .\" .\" Portions of this software were developed for the FreeBSD Project by .\" ThinkSec AS and NAI Labs, the Security Research Division of Network .\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 .\" ("CBOSS"), as part of the DARPA CHATS research program. .\" .\" 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 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 February 1, 2005 .Dt PAM_EXEC 8 .Os .Sh NAME .Nm pam_exec .Nd Exec PAM module .Sh SYNOPSIS .Op Ar service-name .Ar module-type .Ar control-flag .Pa pam_exec .Op Ar arguments .Sh DESCRIPTION The exec service module for PAM executes the program designated by its first argument, with its remaining arguments as command-line arguments. The child's environment is set to the current PAM environment list, as returned by .Xr pam_getenvlist 3 . In addition, the following PAM items are exported as environment variables: .Ev PAM_RHOST , .Ev PAM_RUSER , .Ev PAM_SERVICE , .Ev PAM_TTY , and .Ev PAM_USER . .Sh SEE ALSO -.Xr pam.conf 5 , .Xr pam_get_item 3 , +.Xr pam.conf 5 , .Xr pam 8 .Sh AUTHORS The .Nm module and this manual page were developed for the .Fx Project by ThinkSec AS and NAI Labs, the Security Research Division of Network Associates, Inc.\& under DARPA/SPAWAR contract N66001-01-C-8035 .Pq Dq CBOSS , as part of the DARPA CHATS research program. Index: head/lib/libsdp/sdp.3 =================================================================== --- head/lib/libsdp/sdp.3 (revision 147401) +++ head/lib/libsdp/sdp.3 (revision 147402) @@ -1,415 +1,415 @@ .\" Copyright (c) 2003 Maksim Yevmenkin .\" 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. .\" .\" $Id: sdp.3,v 1.1 2003/09/07 20:34:19 max Exp $ .\" $FreeBSD$ .\" -.Dd September 7, 2003 +.Dd May 27, 2005 .Dt SDP 3 .Os .Sh NAME .Nm SDP_GET8 , .Nm SDP_GET16 , .Nm SDP_GET32 , .Nm SDP_GET64 , .Nm SDP_GET128 , .Nm SDP_GET_UUID128 , .Nm SDP_PUT8 , .Nm SDP_PUT16 , .Nm SDP_PUT32 , .Nm SDP_PUT64 , .Nm SDP_PUT128 , .Nm SDP_PUT_UUID128 , .Nm sdp_open , .Nm sdp_open_local , .Nm sdp_close , .Nm sdp_error , .Nm sdp_search , .Nm sdp_attr2desc , .Nm sdp_uuid2desc .Nd Bluetooth SDP routines .Sh LIBRARY .Lb libsdp .Sh SYNOPSIS .In bluetooth.h .In sdp.h .Fn SDP_GET8 "b" "cp" .Fn SDP_GET16 "s" "cp" .Fn SDP_GET32 "l" "cp" .Fn SDP_GET64 "l" "cp" .Fn SDP_GET128 "l" "cp" .Fn SDP_GET_UUID128 "l" "cp" .Fn SDP_PUT8 "b" "cp" .Fn SDP_PUT16 "s" "cp" .Fn SDP_PUT32 "l" "cp" .Fn SDP_PUT64 "l" "cp" .Fn SDP_PUT128 "l" "cp" .Fn SDP_PUT_UUID128 "l" "cp" .Ft "void *" .Fn sdp_open "bdaddr_t const *l" "bdaddr_t const *r" .Ft "void *" .Fn sdp_open_local "char const *control" .Ft int32_t .Fn sdp_close "void *xs" .Ft int32_t .Fn sdp_error "void *xs" .Ft int32_t .Fo sdp_search .Fa "void *xs" "uint32_t plen" "uint16_t const *pp" "uint32_t alen" .Fa "uint32_t const *ap" "uint32_t vlen" "sdp_attr_t *vp" .Fc .Ft "char const * const" .Fn sdp_attr2desc "uint16_t attr" .Ft "char const * const" .Fn sdp_uuid2desc "uint16_t uuid" .Ft int32_t .Fo sdp_register_service .Fa "void *xss" "uint16_t uuid" "bdaddr_p const bdaddr" "uint8_t const *data" .Fa "uint32_t datalen" "uint32_t *handle" .Fc .Ft int32_t .Fn sdp_unregister_service "void *xss" "uint32_t handle" .Ft int32_t .Fo sdp_change_service .Fa "void *xss" "uint32_t handle" "uint8_t const *data" "uint32_t datalen" .Fc .Sh DESCRIPTION The .Fn SDP_GET8 , .Fn SDP_GET16 , .Fn SDP_GET32 , .Fn SDP_GET64 and .Fn SDP_GET128 macros are used to get byte, short, long, long long and 128-bit integer from the buffer pointed by .Fa cp pointer. The pointer is automatically advanced. .Pp The .Fn SDP_PUT8 , .Fn SDP_PUT16 , .Fn SDP_PUT32 , .Fn SDP_PUT64 and .Fn SDP_PUT128 macros are used to put byte, short, long, long long and 128-bit integer into the buffer pointed by .Fa cp pointer. The pointer is automatically advanced. .Pp .Fn SDP_GET_UUID128 and .Fn SDP_PUT_UUID128 macros are used to get and put 128-bit UUID into the buffer pointed by .Fa cp pointer. The pointer is automatically advanced. .Pp The .Fn sdp_open and .Fn sdp_open_local functions each return a pointer to an opaque object describing SDP session. The .Fa l argument passed to .Fn sdp_open function should point to a source BD_ADDR. If source BD_ADDR is .Dv NULL then source address .Dv NG_HCI_BDADDR_ANY is used. The .Fa r argument passed to .Fn sdp_open function should point to a .Pf non- Dv NULL remote BD_ADDR. Remote BD_ADDR cannot be .Dv NG_HCI_BDADDR_ANY . The .Fn sdp_open_local function takes path to the control socket and opens a connection to a local SDP server. If path to the control socket is .Dv NULL then default .Pa /var/run/sdp path will be used. .Pp The .Fn sdp_close function terminates active SDP session and deletes SDP session object. The .Fa xs parameter should point to a valid SDP session object created with .Fn sdp_open or .Fn sdp_open_local . .Pp The .Fn sdp_error function returns last error that is stored inside SDP session object. The .Fa xs parameter should point to a valid SDP session object created with .Fn sdp_open or .Fn sdp_open_local . The error value returned can be converted to a human readable message by calling .Xr strerror 3 function. .Pp The .Fn sdp_search function is used to perform SDP Service Search Attribute Request. The .Fa xs parameter should point to a valid SDP session object created with .Fn sdp_open or .Fn sdp_open_local . The .Fa pp parameter is a Service Search Pattern - an array of one or more Service Class IDs. The maximum number of Service Class IDs in the array is 12. The .Fa plen parameter is the length of the Service Search pattern. The .Fa ap parameter is an Attribute ID Range List - an array of one or more SDP Attribute ID Range. Each attribute ID Range is encoded as a 32-bit unsigned integer data element, where the high order 16 bits are interpreted as the beginning attribute ID of the range and the low order 16 bits are interpreted as the ending attribute ID of the range. The attribute IDs contained in the Attribute ID Ranges List must be listed in ascending order without duplication of any attribute ID values. Note that all attributes may be requested by specifying a range of 0x0000-0xFFFF. The .Fa alen parameter is the length of the Attribute ID Ranges List. The .Fn SDP_ATTR_RANGE "lo" "hi" macro can be used to prepare Attribute ID Range. The .Fa vp parameter should be an array of .Vt sdp_attr_t structures. Each .Vt sdp_attr_t structure describes single SDP attribute and defined as follows: .Bd -literal -offset indent struct sdp_attr { uint16_t flags; #define SDP_ATTR_OK (0 << 0) #define SDP_ATTR_INVALID (1 << 0) #define SDP_ATTR_TRUNCATED (1 << 1) uint16_t attr; /* SDP_ATTR_xxx */ uint32_t vlen; /* length of the value[] in bytes */ uint8_t *value; /* base pointer */ }; typedef struct sdp_attr sdp_attr_t; typedef struct sdp_attr * sdp_attr_p; .Ed .Pp The caller of the .Fn sdp_search function is expected to prepare the array of .Vt sdp_attr structures and for each element of the array both .Va vlen and .Va value must be set. The .Fn sdp_search function will fill each .Vt sdp_attr_t structure with attribute and value, i.e., it will set .Va flags , .Va attr and .Va vlen fields. The actual value of the attribute will be copied into .Va value buffer. Note: attributes are returned in the order they appear in the Service Search Attribute Response. SDP server could return several attributes for the same record. In this case the order of the attributes will be: all attributes for the first records, then all attributes for the secord record etc. .Pp The .Fn sdp_attr2desc and .Fn sdp_uuid2desc functions each take a numeric attribute ID/UUID value and convert it to a human readable description. .Pp The .Fn sdp_register_service function is used to register service with the local SDP server. The .Fa xss parameter should point to a valid SDP session object obtained from .Fn sdp_open_local . The .Fa uuid parameter is a SDP Service Class ID for the service to be registered. The .Fa bdaddr parameter should point to a valid BD_ADDR. The service will be only advertised if request was received by the local device with .Fa bdaddr . If .Fa bdaddr is set to .Dv NG_HCI_BDADDR_ANY then the service will be advertised to any remote devices that queries for it. The .Fa data and .Fa datalen parameters specify data and size of the data for the service. Upon successful return .Fn sdp_register_service will populate .Fa handle with the SDP record handle. This parameter is optional and can be set to .Dv NULL . .Pp The .Fn sdp_unregister_service function is used to unregister service with the local SDP server. The .Fa xss parameter should point to a valid SDP session object obtained from .Fn sdp_open_local . The .Fa handle parameter should contain a valid SDP record handle of the service to be unregistered. .Pp The .Fn sdp_change_service function is used to change data associated with the existing service on the local SDP server. The .Fa xss parameter should point to a valid SDP session object obtained from .Fn sdp_open_local . The .Fa handle parameter should contain a valid SDP record handle of the service to be changed. The .Fa data and .Fa datalen parameters specify data and size of the data for the service. .Sh CAVEAT When registering services with the local SDP server the application must keep the SDP session open. If SDP session is closed then the local SDP server will remove all services that were registered over the session. The application is allowed to change or unregister service if it was registered over the same session. .Sh EXAMPLES The following example shows how to get .Dv SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST attribute for the .Dv SDP_SERVICE_CLASS_SERIAL_PORT service from the remote device. .Bd -literal -offset indent bdaddr_t remote; uint8_t buffer[1024]; void *ss = NULL; uint16_t serv = SDP_SERVICE_CLASS_SERIAL_PORT; uint32_t attr = SDP_ATTR_RANGE( SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST, SDP_ATTR_PROTOCOL_DESCRIPTOR_LIST); sdp_attr_t proto = { SDP_ATTR_INVALID,0,sizeof(buffer),buffer }; /* Obtain/set remote BDADDR here */ if ((ss = sdp_open(NG_HCI_BDADDR_ANY, remote)) == NULL) /* exit ENOMEM */ if (sdp_error(ss) != 0) /* exit sdp_error(ss) */ if (sdp_search(ss, 1, &serv, 1, &attr, 1, &proto) != 0) /* exit sdp_error(ss) */ if (proto.flags != SDP_ATTR_OK) /* exit see proto.flags for details */ /* If we got here then we have attribute value in proto.value */ .Ed .Sh DIAGNOSTICS Both .Fn sdp_open and .Fn sdp_open_local will return .Dv NULL if memory allocation for the new SDP session object fails. If the new SDP object was created then caller is still expected to call .Fn sdp_error to check if there was connection error. .Pp The .Fn sdp_search , .Fn sdp_register_service , .Fn sdp_unregister_service and .Fn sdp_change_service functions return non-zero value on error. The caller is expected to call .Fn sdp_error to find out more about error. .Sh SEE ALSO .Xr bluetooth 3 , .Xr strerror 3 , .Xr sdpcontrol 8 , .Xr sdpd 8 .Sh AUTHORS .An Maksim Yevmenkin Aq m_evmenkin@yahoo.com .Sh BUGS Most likely. Please report bugs if found. Index: head/lib/msun/man/fenv.3 =================================================================== --- head/lib/msun/man/fenv.3 (revision 147401) +++ head/lib/msun/man/fenv.3 (revision 147402) @@ -1,289 +1,289 @@ .\" Copyright (c) 2004 David Schultz .\" 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 March 16, 2005 .Dt FENV 3 .Os .Sh NAME .Nm feclearexcept , .Nm fegetexceptflag , .Nm feraiseexcept , .Nm fesetexceptflag , .Nm fetestexcept , .Nm fegetround , .Nm fesetround , .Nm fegetenv , .Nm feholdexcept , .Nm fesetenv , .Nm feupdateenv , .Nm feenableexcept , .Nm fedisableexcept , .Nm fegetexcept .Nd floating-point environment control .Sh LIBRARY .Lb libm .Sh SYNOPSIS .In fenv.h .Fd "#pragma STDC FENV_ACCESS ON" .Ft int .Fn feclearexcept "int excepts" .Ft int .Fn fegetexceptflag "fexcept_t *flagp" "int excepts" .Ft int .Fn feraiseexcept "int excepts" .Ft int .Fn fesetexceptflag "const fexcept_t *flagp" "int excepts" .Ft int .Fn fetestexcept "int excepts" .Ft int .Fn fegetround void .Ft int .Fn fesetround "int round" .Ft int .Fn fegetenv "fenv_t *envp" .Ft int .Fn feholdexcept "fenv_t *envp" .Ft int .Fn fesetenv "const fenv_t *envp" .Ft int .Fn feupdateenv "const fenv_t *envp" .Ft int .Fn feenableexcept "int excepts" .Ft int .Fn fedisableexcept "int excepts" .Ft int -.Fn fegetexcept "void" +.Fn fegetexcept void .Sh DESCRIPTION The .In fenv.h routines manipulate the floating-point environment, which includes the exception flags and rounding modes defined in .St -ieee754 . .Ss Exceptions Exception flags are set as side-effects of floating-point arithmetic operations and math library routines, and they remain set until explicitly cleared. The following macros expand to bit flags of type .Vt int representing the five standard floating-point exceptions. .Bl -tag -width ".Dv FE_DIVBYZERO" .It Dv FE_DIVBYZERO A divide-by-zero exception occurs when the program attempts to divide a finite non-zero number by zero. .It Dv FE_INEXACT An inexact exception is raised whenever there is a loss of precision due to rounding. .It Dv FE_INVALID Invalid operation exceptions occur when a program attempts to perform calculations for which there is no reasonable representable answer. For instance, subtraction of infinities, division of zero by zero, ordered comparison involving \*(Nas, and taking the square root of a negative number are all invalid operations. .It Dv FE_OVERFLOW An overflow exception occurs when the magnitude of the result of a computation is too large to fit in the destination type. .It Dv FE_UNDERFLOW Underflow occurs when the result of a computation is too close to zero to be represented as a non-zero value in the destination type. .El .Pp Additionally, the .Dv FE_ALL_EXCEPT macro expands to the bitwise OR of the above flags and any architecture-specific flags. Combinations of these flags are passed to the .Fn feclearexcept , .Fn fegetexceptflag , .Fn feraiseexcept , .Fn fesetexceptflag , and .Fn fetestexcept functions to clear, save, raise, restore, and examine the processor's floating-point exception flags, respectively. .Pp Exceptions may be .Em unmasked with .Fn feenableexcept and masked with .Fn fedisableexcept . Unmasked exceptions cause a trap when they are produced, and all exceptions are masked by default. The current mask can be tested with .Fn fegetexcept . .Ss Rounding Modes .St -ieee754 specifies four rounding modes. These modes control the direction in which results are rounded from their exact values in order to fit them into binary floating-point variables. The four modes correspond with the following symbolic constants. .Bl -tag -width ".Dv FE_TOWARDZERO" .It Dv FE_TONEAREST Results are rounded to the closest representable value. If the exact result is exactly half way between two representable values, the value whose last binary digit is even (zero) is chosen. This is the default mode. .It Dv FE_DOWNWARD Results are rounded towards negative \*[If]. .It Dv FE_UPWARD Results are rounded towards positive \*[If]. .It Dv FE_TOWARDZERO Results are rounded towards zero. .El .Pp The .Fn fegetround and .Fn fesetround functions query and set the rounding mode. .Ss Environment Control The .Fn fegetenv and .Fn fesetenv functions save and restore the floating-point environment, which includes exception flags, the current exception mask, the rounding mode, and possibly other implementation-specific state. The .Fn feholdexcept function behaves like .Fn fegetenv , but with the additional effect of clearing the exception flags and installing a .Em non-stop mode. In non-stop mode, floating-point operations will set exception flags as usual, but no .Dv SIGFPE signals will be generated as a result. Non-stop mode is the default, but it may be altered by non-standard mechanisms. .\" XXX Mention fe[gs]etmask() here after the interface is finalized .\" XXX and ready to be officially documented. The .Fn feupdateenv function restores a saved environment similarly to .Fn fesetenv , but it also re-raises any floating-point exceptions from the old environment. .Pp The macro .Dv FE_DFL_ENV expands to a pointer to the default environment. .Sh CAVEATS The FENV_ACCESS pragma can be enabled with .Dl "#pragma STDC FENV_ACCESS ON" and disabled with the .Dl "#pragma STDC FENV_ACCESS OFF" directive. This lexically-scoped annotation tells the compiler that the program may access the floating-point environment, so optimizations that would violate strict IEEE-754 semantics are disabled. If execution reaches a block of code for which .Dv FENV_ACCESS is off, the floating-point environment will become undefined. .Sh EXAMPLES The following routine computes the square root function. It explicitly raises an invalid exception on appropriate inputs using .Fn feraiseexcept . It also defers inexact exceptions while it computes intermediate values, and then it allows an inexact exception to be raised only if the final answer is inexact. .Bd -literal -offset indent #pragma STDC FENV_ACCESS ON double sqrt(double n) { double x = 1.0; fenv_t env; if (isnan(n) || n < 0.0) { feraiseexcept(FE_INVALID); return (NAN); } if (isinf(n) || n == 0.0) return (n); feholdexcept(&env); while (fabs((x * x) - n) > DBL_EPSILON * 2 * x) x = (x / 2) + (n / (2 * x)); if (x * x == n) feclearexcept(FE_INEXACT); feupdateenv(&env); return (x); } .Ed .Sh SEE ALSO .Xr cc 1 , .Xr feclearexcept 3 , .Xr fedisableexcept 3 , .Xr feenableexcept 3 , .Xr fegetenv 3 , .Xr fegetexcept 3 , .Xr fegetexceptflag 3 , .Xr fegetround 3 , .Xr feholdexcept 3 , .Xr feraiseexcept 3 , .Xr fesetenv 3 , .Xr fesetexceptflag 3 , .Xr fesetround 3 , .Xr fetestexcept 3 , .Xr feupdateenv 3 , .Xr fpgetprec 3 , .Xr fpsetprec 3 .Sh STANDARDS Except as noted below, .In fenv.h conforms to .St -isoC-99 . The .Fn feenableexcept , .Fn fedisableexcept , and .Fn fegetexcept routines are extensions. .Sh HISTORY The .In fenv.h header first appeared in .Fx 5.3 . It supersedes the non-standard routines defined in .In ieeefp.h and documented in .Xr fpgetround 3 . .Sh BUGS The .Dv FENV_ACCESS pragma is unimplemented in the system compiler. However, non-constant expressions generally produce the correct side-effects at low optimization levels. .Pp On the Alpha platform, .Xr cc 1 must be passed the .Fl mieee-with-inexact mfp-rounding-mode=d options in order to generate code that has the standard side-effects and uses the specified rounding modes. Index: head/lib/msun/man/lround.3 =================================================================== --- head/lib/msun/man/lround.3 (revision 147401) +++ head/lib/msun/man/lround.3 (revision 147402) @@ -1,112 +1,112 @@ .\" Copyright (c) 2005 David Schultz .\" 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 April 7, 2005 .Dt LROUND 3 .Os .Sh NAME .Nm llround , .Nm llroundf , .Nm llroundl , .Nm lround , .Nm lroundf , .Nm lroundl .Nd "convert to nearest integral value" .Sh LIBRARY .Lb libm .Sh SYNOPSIS .In math.h .Ft "long long" .Fn llround "double x" .Ft "long long" .Fn llroundf "float x" .Ft "long long" .Fn llroundl "long double x" .Ft long .Fn lround "double x" .Ft long .Fn lroundf "float x" .Ft long .Fn lroundl "long double x" .Sh DESCRIPTION The .Fn lround function returns the integer nearest to its argument .Fa x , rounding away from zero in halfway cases. If the rounded result is too large to be represented as a .Vt long value, an invalid exception is raised and the return value is undefined. Otherwise, if .Fa x is not an integer, .Fn lround may raise an inexact exception. When the rounded result is representable as a .Vt long , the expression .Fn lround x is equivalent to .Po Vt long Pc Ns Fn round x (although the former may be more efficient). .Pp The .Fn llround , .Fn llroundf , .Fn llroundl , .Fn lroundf and .Fn lroundl functions differ from .Fn lround only in their input and output types. .Sh SEE ALSO .Xr lrint 3 , .Xr math 3 , .Xr rint 3 , .Xr round 3 .Sh STANDARDS The .Fn llround , .Fn llroundf , .Fn llroundl , .Fn lround , .Fn lroundf , and .Fn lroundl functions conform to .St -isoC-99 . .Sh HISTORY The -.Ft float +.Vt float and -.Ft double +.Vt double versions of these routines first appeared in .Fx 5.4 . The -.Ft long double +.Vt "long double" versions appeared in .Fx 6.0 . Index: head/lib/msun/man/round.3 =================================================================== --- head/lib/msun/man/round.3 (revision 147401) +++ head/lib/msun/man/round.3 (revision 147402) @@ -1,80 +1,80 @@ .\" Copyright (c) 2003, Steven G. Kargl .\" 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 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 April 7, 2005 .Dt ROUND 3 .Os .Sh NAME .Nm round , .Nm roundf , .Nm roundl .Nd round to nearest integral value .Sh LIBRARY .Lb libm .Sh SYNOPSIS .In math.h .Ft double .Fn round "double x" .Ft float .Fn roundf "float x" -.Ft long double +.Ft "long double" .Fn roundl "long double x" .Sh DESCRIPTION The .Fn round , .Fn roundf , and .Fn roundl functions return the nearest integral value to .Fa x ; if .Fa x lies halfway between two integral values, then these functions return the integral value with the larger absolute value (i.e., they round away from zero). .Sh SEE ALSO .Xr ceil 3 , .Xr floor 3 , .Xr ieee 3 , .Xr lrint 3 , .Xr lround 3 , .Xr math 3 , .Xr rint 3 , .Xr trunc 3 .Sh STANDARDS These functions conform to .St -isoC-99 . .Sh HISTORY The .Fn round and .Fn roundf functions appeared in .Fx 5.3 . The .Fn roundl function appeared in .Fx 6.0 . Index: head/lib/msun/man/trunc.3 =================================================================== --- head/lib/msun/man/trunc.3 (revision 147401) +++ head/lib/msun/man/trunc.3 (revision 147402) @@ -1,80 +1,80 @@ .\" Copyright (c) 2004, 2005 David Schultz .\" 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 April 16, 2005 .Dt TRUNC 3 .Os .Sh NAME .Nm trunc , .Nm truncf , .Nm truncl .Nd nearest integral value with magnitude less than or equal to |x| .Sh LIBRARY .Lb libm .Sh SYNOPSIS .In math.h .Ft double .Fn trunc "double x" .Ft float .Fn truncf "float x" -.Ft long double +.Ft "long double" .Fn truncl "long double x" .Sh DESCRIPTION The .Fn trunc , .Fn truncf , and .Fn truncl functions return the nearest integral value with magnitude less than or equal to .Pf | Fa x Ns | . They are equivalent to .Fn rint , .Fn rintf , and .Fn rintl , respectively, in the .Dv FE_TOWARDZERO rounding mode. .Sh SEE ALSO .Xr ceil 3 , .Xr fesetround 3 , .Xr floor 3 , .Xr math 3 , .Xr nextafter 3 , .Xr rint 3 , .Xr round 3 .Sh STANDARDS The .Fn trunc , .Fn truncf , and .Fn truncl functions conform to .St -isoC-99 . .Sh HISTORY These routines first appeared in .Fx 5.3 .