From 8746d263e1451855025dc83dde5176cc9f1fbe3f Mon Sep 17 00:00:00 2001 From: ru Date: Wed, 18 Dec 2002 12:45:11 +0000 Subject: mdoc(7) police: "The .Fn function". --- lib/libc/compat-43/creat.2 | 6 +++-- lib/libc/compat-43/gethostid.3 | 8 ++++-- lib/libc/compat-43/killpg.2 | 10 +++++--- lib/libc/compat-43/sigpause.2 | 10 +++++--- lib/libc/compat-43/sigsetmask.2 | 14 ++++++++--- lib/libc/compat-43/sigvec.2 | 8 ++++-- lib/libc/db/man/dbm.3 | 32 ++++++++++++++++++++++++ lib/libc/db/man/dbopen.3 | 12 ++++++--- lib/libc/db/man/mpool.3 | 12 ++++++--- lib/libc/gmon/moncontrol.3 | 2 ++ lib/libc/i386/sys/i386_set_watch.3 | 8 ++++++ lib/libc/locale/isblank.3 | 2 ++ lib/libc/locale/rune.3 | 2 ++ lib/libc/net/ethers.3 | 4 +++ lib/libc/net/getaddrinfo.3 | 4 ++- lib/libc/net/gethostbyname.3 | 2 ++ lib/libc/net/getipnodebyname.3 | 15 ++++++++++- lib/libc/net/hesiod.3 | 19 +++++++++++++- lib/libc/net/inet6_option_space.3 | 8 ++++++ lib/libc/net/inet6_rthdr_space.3 | 10 ++++++++ lib/libc/net/iso_addr.3 | 4 +++ lib/libc/net/linkaddr.3 | 4 +++ lib/libc/net/rcmd.3 | 6 +++++ lib/libc/net/sockatmark.3 | 2 +- lib/libc/posix1e/acl_add_perm.3 | 2 ++ lib/libc/posix1e/acl_calc_mask.3 | 2 ++ lib/libc/posix1e/acl_clear_perms.3 | 2 ++ lib/libc/posix1e/acl_copy_entry.3 | 2 ++ lib/libc/posix1e/acl_create_entry.3 | 2 ++ lib/libc/posix1e/acl_delete.3 | 2 ++ lib/libc/posix1e/acl_delete_entry.3 | 2 ++ lib/libc/posix1e/acl_delete_perm.3 | 2 ++ lib/libc/posix1e/acl_from_text.3 | 2 ++ lib/libc/posix1e/acl_get.3 | 4 +++ lib/libc/posix1e/acl_get_entry.3 | 2 ++ lib/libc/posix1e/acl_get_perm_np.3 | 2 ++ lib/libc/posix1e/acl_get_permset.3 | 2 ++ lib/libc/posix1e/acl_get_qualifier.3 | 2 ++ lib/libc/posix1e/acl_get_tag_type.3 | 2 ++ lib/libc/posix1e/acl_set_permset.3 | 2 ++ lib/libc/posix1e/acl_set_qualifier.3 | 2 ++ lib/libc/posix1e/acl_set_tag_type.3 | 2 ++ lib/libc/posix1e/acl_to_text.3 | 2 ++ lib/libc/regex/regex.3 | 41 ++++++++++++++++++++++-------- lib/libc/rpc/bindresvport.3 | 6 +++++ lib/libc/rpc/des_crypt.3 | 6 +++++ lib/libc/rpc/getnetconfig.3 | 36 +++++++++++++++++++++++++++ lib/libc/rpc/getnetpath.3 | 16 ++++++++++++ lib/libc/rpc/getrpcent.3 | 10 ++++++++ lib/libc/rpc/getrpcport.3 | 2 ++ lib/libc/rpc/publickey.3 | 2 ++ lib/libc/rpc/rpc_clnt_calls.3 | 4 +++ lib/libc/rpc/rpc_clnt_create.3 | 10 ++++++++ lib/libc/rpc/rpc_secure.3 | 48 +++++++++++++++++++++++++++--------- lib/libc/rpc/rpc_soc.3 | 2 ++ lib/libc/rpc/rpc_svc_calls.3 | 2 ++ lib/libc/rpc/rpc_svc_create.3 | 8 ++++++ lib/libc/rpc/rpcbind.3 | 2 ++ lib/libc/rpc/rtime.3 | 2 ++ lib/libc/stdio/fclose.3 | 2 ++ lib/libc/stdio/fwide.3 | 2 ++ lib/libc/stdio/mktemp.3 | 2 ++ lib/libc/stdio/printf.3 | 16 +++++++++--- lib/libc/stdio/tmpnam.3 | 4 ++- lib/libc/stdlib/getopt_long.3 | 2 ++ lib/libc/stdlib/lsearch.3 | 2 ++ lib/libc/stdlib/malloc.3 | 4 ++- lib/libc/stdlib/qsort.3 | 12 ++++++--- lib/libc/stdlib/rand.3 | 2 ++ lib/libc/stdlib/realpath.3 | 2 +- lib/libc/stdlib/tsearch.3 | 20 +++++++++++---- lib/libc/stdtime/ctime.3 | 14 ++++++++++- lib/libc/string/strcpy.3 | 2 ++ lib/libc/string/strlcpy.3 | 1 + lib/libc/string/strtok.3 | 2 ++ lib/libc/xdr/xdr.3 | 2 ++ 76 files changed, 468 insertions(+), 64 deletions(-) (limited to 'lib') diff --git a/lib/libc/compat-43/creat.2 b/lib/libc/compat-43/creat.2 index dcfa4c5..6f8fc6f 100644 --- a/lib/libc/compat-43/creat.2 +++ b/lib/libc/compat-43/creat.2 @@ -50,7 +50,9 @@ This interface is made obsolete by: .Ef .Xr open 2 . .Pp -.Fn Creat +The +.Fn creat +function is the same as: .Bd -literal -offset indent open(path, O_CREAT | O_TRUNC | O_WRONLY, mode); @@ -60,5 +62,5 @@ open(path, O_CREAT | O_TRUNC | O_WRONLY, mode); .Sh HISTORY The .Fn creat -function call appeared in +function appeared in .At v6 . diff --git a/lib/libc/compat-43/gethostid.3 b/lib/libc/compat-43/gethostid.3 index 27b6d66..6a7c98b 100644 --- a/lib/libc/compat-43/gethostid.3 +++ b/lib/libc/compat-43/gethostid.3 @@ -48,14 +48,18 @@ .Ft void .Fn sethostid "long hostid" .Sh DESCRIPTION -.Fn Sethostid +The +.Fn sethostid +function establishes a 32-bit identifier for the current processor that is intended to be unique among all UNIX systems in existence. This is normally a DARPA Internet address for the local machine. This call is allowed only to the super-user and is normally performed at boot time. .Pp -.Fn Gethostid +The +.Fn gethostid +function returns the 32-bit identifier for the current processor. .Pp This function has been deprecated. diff --git a/lib/libc/compat-43/killpg.2 b/lib/libc/compat-43/killpg.2 index 5f42008..937140f 100644 --- a/lib/libc/compat-43/killpg.2 +++ b/lib/libc/compat-43/killpg.2 @@ -46,7 +46,9 @@ .Ft int .Fn killpg "pid_t pgrp" "int sig" .Sh DESCRIPTION -.Fn Killpg +The +.Fn killpg +function sends the signal .Fa sig to the process group @@ -68,7 +70,9 @@ to any process that is a descendant of the current process. .Sh RETURN VALUES .Rv -std killpg .Sh ERRORS -.Fn Killpg +The +.Fn killpg +function will fail and no signal will be sent if: .Bl -tag -width Er .It Bq Er EINVAL @@ -92,5 +96,5 @@ of the sending process. .Sh HISTORY The .Fn killpg -function call appeared in +function appeared in .Bx 4.0 . diff --git a/lib/libc/compat-43/sigpause.2 b/lib/libc/compat-43/sigpause.2 index 1af1064..611b06c 100644 --- a/lib/libc/compat-43/sigpause.2 +++ b/lib/libc/compat-43/sigpause.2 @@ -48,7 +48,9 @@ .Sy This interface is made obsolete by .Xr sigsuspend 2 . .Pp -.Fn Sigpause +The +.Fn sigpause +function assigns .Fa sigmask to the set of masked signals @@ -57,7 +59,9 @@ on return the set of masked signals is restored. .Fa Sigmask is usually 0 to indicate that no signals are to be blocked. -.Fn Sigpause +The +.Fn sigpause +function always terminates by being interrupted, returning -1 with .Va errno set to @@ -72,6 +76,6 @@ set to .Sh HISTORY The .Fn sigpause -function call appeared in +function appeared in .Bx 4.2 and has been deprecated. diff --git a/lib/libc/compat-43/sigsetmask.2 b/lib/libc/compat-43/sigsetmask.2 index f30bcd1..8e8d78f 100644 --- a/lib/libc/compat-43/sigsetmask.2 +++ b/lib/libc/compat-43/sigsetmask.2 @@ -55,13 +55,17 @@ This interface is made obsolete by: .Ef .Xr sigprocmask 2 . .Pp -.Fn Sigsetmask +The +.Fn sigsetmask +function sets the current signal mask to the specified .Fa mask . Signals are blocked from delivery if the corresponding bit in .Fa mask is a 1. -.Fn Sigblock +The +.Fn sigblock +function adds the signals in the specified .Fa mask to the current signal mask, @@ -80,9 +84,11 @@ or .Dv SIGSTOP to be blocked. .Sh RETURN VALUES -.Fn Sigblock +The +.Fn sigblock and .Fn sigsetmask +functions return the previous set of masked signals. .Sh SEE ALSO .Xr kill 2 , @@ -96,6 +102,6 @@ The .Fn sigsetmask and .Fn sigblock -function calls first appeared in +functions first appeared in .Bx 4.2 and have been deprecated. diff --git a/lib/libc/compat-43/sigvec.2 b/lib/libc/compat-43/sigvec.2 index 25f1b14..3354136 100644 --- a/lib/libc/compat-43/sigvec.2 +++ b/lib/libc/compat-43/sigvec.2 @@ -116,7 +116,9 @@ adding the signal to be delivered, and .Em or Ns 'ing in the signal mask associated with the handler to be invoked. .Pp -.Fn Sigvec +The +.Fn sigvec +function assigns a handler for a specific signal. If .Fa vec is non-zero, it @@ -258,7 +260,9 @@ hence it should not be used if backward compatibility is needed. .Sh RETURN VALUES .Rv -std sigvec .Sh ERRORS -.Fn Sigvec +The +.Fn sigvec +function will fail and no new signal handler will be installed if one of the following occurs: .Bl -tag -width Er diff --git a/lib/libc/db/man/dbm.3 b/lib/libc/db/man/dbm.3 index 961ea85..a78d35a 100644 --- a/lib/libc/db/man/dbm.3 +++ b/lib/libc/db/man/dbm.3 @@ -73,7 +73,9 @@ typedef struct { } datum; .Ed .Pp +The .Fn dbm_open base flags mode +function opens or creates a database. .Fa base is the basename of the file containing @@ -105,19 +107,27 @@ The pointer returned by identifies the database and is the .Fa db argument to the other functions. +The .Fn dbm_open +function returns .Dv NULL and sets .Va errno if there were any errors. .Pp +The .Fn dbm_close db +function closes the database. +The .Fn dbm_close +function normally returns zero. .Pp +The .Fn dbm_store db key data flags +function inserts or replaces an entry in the database. .Fa flags is either @@ -132,7 +142,9 @@ and the database already contains an entry for .Fa key , that entry is not replaced. Otherwise the entry is replaced or inserted. +The .Fn dbm_store +function normally returns zero but returns 1 if the entry could not be inserted (because .Fa flags @@ -144,7 +156,9 @@ already exists) or returns -1 and sets .Va errno if there were any errors. .Pp +The .Fn dbm_fetch db key +function returns .Dv NULL or the @@ -152,38 +166,56 @@ or the corresponding to .Fa key . .Pp +The .Fn dbm_delete db key +function deletes the entry for .Fa key . +The .Fn dbm_delete +function normally returns zero but returns 1 if there was no entry with .Fa key in the database or returns -1 and sets .Va errno if there were any errors. .Pp +The .Fn dbm_firstkey db +function returns the first key in the database. +The .Fn dbm_nextkey db +function returns subsequent keys. +The .Fn db_firstkey +function must be called before .Fn dbm_nextkey . The order in which keys are returned is unspecified and may appear random. +The .Fn dbm_nextkey +function returns .Dv NULL after all keys have been returned. .Pp +The .Fn dbm_error db +function returns the .Va errno value of the most recent error. +The .Fn dbm_clearerr db +function resets this value to 0 and returns 0. .Pp +The .Fn dbm_dirfno db +function returns the file descriptor to the database. .Sh SEE ALSO .Xr open 2 , diff --git a/lib/libc/db/man/dbopen.3 b/lib/libc/db/man/dbopen.3 index 8fce3b2..44ff657 100644 --- a/lib/libc/db/man/dbopen.3 +++ b/lib/libc/db/man/dbopen.3 @@ -46,7 +46,9 @@ .Ft DB * .Fn dbopen "const char *file" "int flags" "int mode" "DBTYPE type" "const void *openinfo" .Sh DESCRIPTION -.Fn Dbopen +The +.Fn dbopen +function is the library interface to database files. The supported file formats are btree, hashed and UNIX file oriented. The btree format is a representation of a sorted, balanced tree structure. @@ -60,7 +62,9 @@ in their respective manual pages and .Xr recno 3 . .Pp -.Fn Dbopen +The +.Fn dbopen +function opens .Fa file for reading and/or writing. @@ -131,7 +135,9 @@ is each access method will use defaults appropriate for the system and the access method. .Pp -.Fn Dbopen +The +.Fn dbopen +function returns a pointer to a .Ft DB structure on success and diff --git a/lib/libc/db/man/mpool.3 b/lib/libc/db/man/mpool.3 index 38787167..26333b8 100644 --- a/lib/libc/db/man/mpool.3 +++ b/lib/libc/db/man/mpool.3 @@ -167,7 +167,9 @@ any of the following values: The page has been modified and needs to be written to the backing file. .El .Pp -.Fn Mpool_put +The +.Fn mpool_put +function returns 0 on success and -1 if an error occurs. .Pp The function @@ -176,7 +178,9 @@ writes all modified pages associated with the .Ft MPOOL pointer to the backing file. -.Fn Mpool_sync +The +.Fn mpool_sync +function returns 0 on success and -1 if an error occurs. .Pp The @@ -186,7 +190,9 @@ cookie. Modified pages are .Em not written to the backing file. -.Fn Mpool_close +The +.Fn mpool_close +function returns 0 on success and -1 if an error occurs. .Sh ERRORS The diff --git a/lib/libc/gmon/moncontrol.3 b/lib/libc/gmon/moncontrol.3 index 1162178..fb507ab 100644 --- a/lib/libc/gmon/moncontrol.3 +++ b/lib/libc/gmon/moncontrol.3 @@ -63,7 +63,9 @@ where progname is the name of the program, then .Xr gprof 1 can be used to examine the results. .Pp +The .Fn moncontrol +function selectively controls profiling within a program. When the program starts, profiling begins. To stop the collection of histogram ticks and call counts use diff --git a/lib/libc/i386/sys/i386_set_watch.3 b/lib/libc/i386/sys/i386_set_watch.3 index 28f2261..8f02555 100644 --- a/lib/libc/i386/sys/i386_set_watch.3 +++ b/lib/libc/i386/sys/i386_set_watch.3 @@ -44,11 +44,15 @@ .Ft int .Fn i386_set_watch "int watchnum" "unsigned int watchaddr" "int size" "int access" "struct dbreg *d" .Sh DESCRIPTION +The .Fn i386_clr_watch +function will disable the indicated watch point within the specified debug register set. .Pp +The .Fn i386_set_watch +function will set up the specified debug registers as indicated by the parameters. The .Fa watchnum @@ -76,12 +80,16 @@ they manipulate the indicated debug register set. You must use .Xr ptrace 2 to retrieve and install the debug register values for a process. .Sh RETURN VALUES +The .Fn i386_clr_watch +function returns 0 on success, or -1 if .Fa watchnum is invalid (not in the range of 0-3). .Pp +The .Fn i386_set_watch +function will return the .Fa watchnum argument, or the watchnum actually used in the case that diff --git a/lib/libc/locale/isblank.3 b/lib/libc/locale/isblank.3 index 12e54a0..5fdc2ae 100644 --- a/lib/libc/locale/isblank.3 +++ b/lib/libc/locale/isblank.3 @@ -88,6 +88,8 @@ returns non-zero if the character tests true. .Xr multibyte 3 , .Xr ascii 7 .Sh STANDARDS +The .Fn isblank +function conforms to .St -isoC-99 . diff --git a/lib/libc/locale/rune.3 b/lib/libc/locale/rune.3 index 755ac96..a880dee 100644 --- a/lib/libc/locale/rune.3 +++ b/lib/libc/locale/rune.3 @@ -234,7 +234,9 @@ The function returns one of the following values: .Bl -tag -width Er .It Er 0 +The .Fn setrunelocale +function was successful. .It Bq Er EINVAL .Fa locale diff --git a/lib/libc/net/ethers.3 b/lib/libc/net/ethers.3 index 40b5c7d..bfa5955 100644 --- a/lib/libc/net/ethers.3 +++ b/lib/libc/net/ethers.3 @@ -116,12 +116,16 @@ functions map ethernet addresses to their corresponding hostnames as specified in the .Pa /etc/ethers database. +The .Fn ether_ntohost +function converts from ethernet address to hostname, and .Fn ether_hostton converts from hostname to ethernet address. .Sh RETURN VALUES +The .Fn ether_line +function returns zero on success and non-zero if it was unable to parse any part of the supplied line .Ar l . diff --git a/lib/libc/net/getaddrinfo.3 b/lib/libc/net/getaddrinfo.3 index 9ef8898..4dbd771 100644 --- a/lib/libc/net/getaddrinfo.3 +++ b/lib/libc/net/getaddrinfo.3 @@ -1,4 +1,3 @@ -.\" $FreeBSD$ .\" $KAME: getaddrinfo.3,v 1.31 2001/08/05 18:19:38 itojun Exp $ .\" .\" Copyright (c) 1983, 1987, 1991, 1993 @@ -33,6 +32,7 @@ .\" SUCH DAMAGE. .\" .\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 +.\" $FreeBSD$ .\" .Dd May 25, 1995 .Dt GETADDRINFO 3 @@ -274,7 +274,9 @@ must be sufficiently consistent and unambiguous. Here are some problem cases you may encounter: .Bl -bullet .It +The .Fn getaddrinfo +function will fail if the members in the .Fa hints structure are not consistent. diff --git a/lib/libc/net/gethostbyname.3 b/lib/libc/net/gethostbyname.3 index 72cd124..4f4b9dc 100644 --- a/lib/libc/net/gethostbyname.3 +++ b/lib/libc/net/gethostbyname.3 @@ -372,7 +372,9 @@ copied before any subsequent calls overwrite it. Only the Internet address format is currently understood. .Pp +The .Fn gethostbyname2 +function cannot perform .Dv AF_INET6 lookups over NIS. diff --git a/lib/libc/net/getipnodebyname.3 b/lib/libc/net/getipnodebyname.3 index 5860fb8..b564c41 100644 --- a/lib/libc/net/getipnodebyname.3 +++ b/lib/libc/net/getipnodebyname.3 @@ -1,4 +1,3 @@ -.\" $FreeBSD$ .\" $KAME: getipnodebyname.3,v 1.6 2000/08/09 21:16:17 itojun Exp $ .\" .\" Copyright (c) 1983, 1987, 1991, 1993 @@ -33,6 +32,7 @@ .\" SUCH DAMAGE. .\" .\" From: @(#)gethostbyname.3 8.4 (Berkeley) 5/25/95 +.\" $FreeBSD$ .\" .Dd May 25, 1995 .Dt GETIPNODEBYNAME 3 @@ -58,6 +58,7 @@ .Fn freehostent "struct hostent *ptr" .\" .Sh DESCRIPTION +The .Fn getipnodebyname and .Fn getipnodebyaddr @@ -375,18 +376,24 @@ pointer and the value pointed to by equals .Dv HOST_NOT_FOUND . .Pp +The .Fn getipnodebyaddr +function takes almost the same argument as .Xr gethostbyaddr 3 , but adds a pointer to return an error number. Additionally it takes care of IPv4-mapped IPv6 addresses, and IPv4-compatible IPv6 addresses. .Pp +The .Fn getipnodebyname and .Fn getipnodebyaddr +functions dynamically allocate the structure to be returned to the caller. +The .Fn freehostent +function reclaims memory region allocated and returned by .Fn getipnodebyname or @@ -400,9 +407,11 @@ or .El .\" .Sh DIAGNOSTICS +The .Fn getipnodebyname and .Fn getipnodebyaddr +functions returns .Dv NULL on errors. @@ -436,17 +445,21 @@ The meanings of each error code are described in The implementation first appeared in KAME advanced networking kit. .\" .Sh STANDARDS +The .Fn getipnodebyname and .Fn getipnodebyaddr +functions are documented in .Dq Basic Socket Interface Extensions for IPv6 (RFC2553). .\" .Sh BUGS +The .Fn getipnodebyname and .Fn getipnodebyaddr +functions do not handle scoped IPv6 address properly. If you use these functions, your program will not be able to handle scoped IPv6 addresses. diff --git a/lib/libc/net/hesiod.3 b/lib/libc/net/hesiod.3 index 9b9ad1c..d91db9e 100644 --- a/lib/libc/net/hesiod.3 +++ b/lib/libc/net/hesiod.3 @@ -1,5 +1,4 @@ .\" $NetBSD: hesiod.3,v 1.1 1999/01/25 03:43:04 lukem Exp $ -.\" $FreeBSD$ .\" .\" from: #Id: hesiod.3,v 1.9.2.1 1997/01/03 21:02:23 ghudson Exp # .\" @@ -17,6 +16,8 @@ .\" this software for any purpose. It is provided "as is" .\" without express or implied warranty. .\" +.\" $FreeBSD$ +.\" .Dd November 30, 1996 .Dt HESIOD 3 .Os @@ -50,15 +51,21 @@ To perform lookups, you must first initialize a .Fa context , an opaque object which stores information used internally by the library between calls. +The .Fn hesiod_init +function initializes a context, storing a pointer to the context in the location pointed to by the .Fa context argument. +The .Fn hesiod_end +function frees the resources used by a context. .Pp +The .Fn hesiod_resolve +function is the primary interface to the library. If successful, it returns a list of one or more strings giving the records matching @@ -73,7 +80,9 @@ caller's responsibility to call .Fn hesiod_free_list to free the resources used by the returned list. .Pp +The .Fn hesiod_to_bind +function converts .Fa name and @@ -117,19 +126,27 @@ Hesiod calls may fail because of: Insufficient memory was available to carry out the requested operation. .It Bq Er ENOEXEC +The .Fn hesiod_init +function failed because the Hesiod configuration file was invalid. .It Bq Er ECONNREFUSED +The .Fn hesiod_resolve +function failed because no name server could be contacted to answer the query. .It Bq Er EMSGSIZE +The .Fn hesiod_resolve or .Fn hesiod_to_bind +function failed because the query or response was too big to fit into the packet buffers. .It Bq Er ENOENT +The .Fn hesiod_resolve +function failed because the name server had no text records matching .Fa name and diff --git a/lib/libc/net/inet6_option_space.3 b/lib/libc/net/inet6_option_space.3 index 3e1649a..00a9b46 100644 --- a/lib/libc/net/inet6_option_space.3 +++ b/lib/libc/net/inet6_option_space.3 @@ -75,7 +75,9 @@ these functions are all in the header. .\" .Ss inet6_option_space +The .Fn inet6_option_space +function returns the number of bytes required to hold an option when it is stored as ancillary data, including the .Li cmsghdr @@ -105,7 +107,9 @@ one option (appendix B of [RFC-2460]). .\" .Ss inet6_option_init +The .Fn inet6_option_init +function is called once per ancillary data object that will contain either Hop-by-Hop or Destination options. It returns @@ -387,16 +391,20 @@ is not .Dv NULL . .\" .Sh DIAGNOSTICS +The .Fn inet6_option_init and .Fn inet6_option_append +functions return .Li 0 on success or .Li -1 on an error. .Pp +The .Fn inet6_option_alloc +function returns .Dv NULL on an error. diff --git a/lib/libc/net/inet6_rthdr_space.3 b/lib/libc/net/inet6_rthdr_space.3 index 154f514..428d96f 100644 --- a/lib/libc/net/inet6_rthdr_space.3 +++ b/lib/libc/net/inet6_rthdr_space.3 @@ -267,25 +267,33 @@ Note: Addresses are indexed starting at 1, and flags starting at 0, to maintain consistency with the terminology and figures in RFC2460. .\" .Sh DIAGNOSTICS +The .Fn inet6_rthdr_space +function returns 0 on errors. .Pp +The .Fn inet6_rthdr_add , .Fn inet6_rthdr_lasthop and .Fn inet6_rthdr_reverse +functions return 0 on success, and returns -1 on error. .Pp +The .Fn inet6_rthdr_init and .Fn inet6_rthdr_getaddr +functions return .Dv NULL on error. .Pp +The .Fn inet6_rthdr_segments and .Fn inet6_rthdr_getflags +functions return -1 on error. .\" .Sh EXAMPLES @@ -319,5 +327,7 @@ are documented in .Sh BUGS The text was shamelessly copied from RFC2292. .Pp +The .Fn inet6_rthdr_reverse +function is not implemented yet. diff --git a/lib/libc/net/iso_addr.3 b/lib/libc/net/iso_addr.3 index 4407dca..5654ae8 100644 --- a/lib/libc/net/iso_addr.3 +++ b/lib/libc/net/iso_addr.3 @@ -88,9 +88,13 @@ A period following an odd number of bytes has the effect of causing the byte of address being translated to have its higher order bits filled with zeros. .Sh RETURN VALUES +The .Fn iso_ntoa +function always returns a null terminated string. +The .Fn iso_addr +function always returns a pointer to a struct iso_addr. (See .Sx BUGS . ) diff --git a/lib/libc/net/linkaddr.3 b/lib/libc/net/linkaddr.3 index 4b1c6e9..61ebee0 100644 --- a/lib/libc/net/linkaddr.3 +++ b/lib/libc/net/linkaddr.3 @@ -102,9 +102,13 @@ The direct use of these functions is deprecated in favor of the interface; however, portable programs cannot rely on the latter as it is not yet widely implemented. .Sh RETURN VALUES +The .Fn link_ntoa +function always returns a null terminated string. +The .Fn link_addr +function has no return value. (See .Sx BUGS . ) diff --git a/lib/libc/net/rcmd.3 b/lib/libc/net/rcmd.3 index 5367655..3673c81 100644 --- a/lib/libc/net/rcmd.3 +++ b/lib/libc/net/rcmd.3 @@ -286,13 +286,19 @@ is overloaded to mean ``All network ports in use.'' Most of these functions appeared in .Bx 4.2 . +The .Fn rresvport_af +function appeared in RFC2292, and was implemented by the WIDE project for the Hydrangea IPv6 protocol stack kit. +The .Fn rcmd_af +function appeared in draft-ietf-ipngwg-rfc2292bis-01.txt, and was implemented in the WIDE/KAME IPv6 protocol stack kit. +The .Fn iruserok_sa +function appeared in discussion on the IETF ipngwg mailing list, and was implemented in .Fx 4.0 . diff --git a/lib/libc/net/sockatmark.3 b/lib/libc/net/sockatmark.3 index 0cd8427..da073c0 100644 --- a/lib/libc/net/sockatmark.3 +++ b/lib/libc/net/sockatmark.3 @@ -106,7 +106,7 @@ is a descriptor for a file, not a socket. .Sh HISTORY The .Fn sockatmark -function call was introduced by +function was introduced by .St -p1003.1-2001 , to standardize the historical .Dv SIOCATMARK diff --git a/lib/libc/posix1e/acl_add_perm.3 b/lib/libc/posix1e/acl_add_perm.3 index 5649d12..43d04f1 100644 --- a/lib/libc/posix1e/acl_add_perm.3 +++ b/lib/libc/posix1e/acl_add_perm.3 @@ -39,7 +39,9 @@ .Ft int .Fn acl_add_perm "acl_permset_t permset_d" "acl_perm_t perm" .Sh DESCRIPTION +The .Fn acl_add_perm +function is a POSIX.1e call that adds the permission contained in .Fa perm to the permission set diff --git a/lib/libc/posix1e/acl_calc_mask.3 b/lib/libc/posix1e/acl_calc_mask.3 index db3ecfb..48d2678 100644 --- a/lib/libc/posix1e/acl_calc_mask.3 +++ b/lib/libc/posix1e/acl_calc_mask.3 @@ -39,7 +39,9 @@ .Ft int .Fn acl_calc_mask "acl_t *acl_p" .Sh DESCRIPTION +The .Fn acl_calc_mask +function is a POSIX.1e call that calculates and set the permissions associated with the .Dv ACL_MASK diff --git a/lib/libc/posix1e/acl_clear_perms.3 b/lib/libc/posix1e/acl_clear_perms.3 index fb5976f..db026a3 100644 --- a/lib/libc/posix1e/acl_clear_perms.3 +++ b/lib/libc/posix1e/acl_clear_perms.3 @@ -39,7 +39,9 @@ .Ft int .Fn acl_clear_perms "acl_permset_t permset_d" .Sh DESCRIPTION +The .Fn acl_clear_perms +function is a POSIX.1e call that clears all permissions from permissions set .Fa permset_d . .Sh RETURN VALUES diff --git a/lib/libc/posix1e/acl_copy_entry.3 b/lib/libc/posix1e/acl_copy_entry.3 index c6cdf8d..fead89f 100644 --- a/lib/libc/posix1e/acl_copy_entry.3 +++ b/lib/libc/posix1e/acl_copy_entry.3 @@ -39,7 +39,9 @@ .Ft int .Fn acl_copy_entry "acl_entry_t dest_d" "acl_entry_t src_d" .Sh DESCRIPTION +The .Fn acl_copy_entry +function is a POSIX.1e call that copies the contents of ACL entry .Fa src_d to ACL entry diff --git a/lib/libc/posix1e/acl_create_entry.3 b/lib/libc/posix1e/acl_create_entry.3 index 47db02f..fb856ad 100644 --- a/lib/libc/posix1e/acl_create_entry.3 +++ b/lib/libc/posix1e/acl_create_entry.3 @@ -39,7 +39,9 @@ .Ft int .Fn acl_create_entry "acl_t *acl_p" "acl_entry_t *entry_p" .Sh DESCRIPTION +The .Fn acl_create_entry +function is a POSIX.1e call that creates a new ACL entry in the ACL pointed to by .Fa acl_p . diff --git a/lib/libc/posix1e/acl_delete.3 b/lib/libc/posix1e/acl_delete.3 index 220638c..b3fb658 100644 --- a/lib/libc/posix1e/acl_delete.3 +++ b/lib/libc/posix1e/acl_delete.3 @@ -51,7 +51,9 @@ The and .Fn acl_delete_fd_np each allow the deletion of an ACL from a file. +The .Fn acl_delete_def_file +function is a POSIX.1e call that deletes the default ACL from a file (normally a directory) by name; the other two calls are non-portable extensions that allow deleting of arbitrary ACL types from a file/directory by either path diff --git a/lib/libc/posix1e/acl_delete_entry.3 b/lib/libc/posix1e/acl_delete_entry.3 index 45cddb0..86fe7b2 100644 --- a/lib/libc/posix1e/acl_delete_entry.3 +++ b/lib/libc/posix1e/acl_delete_entry.3 @@ -39,7 +39,9 @@ .Ft int .Fn acl_delete_entry "acl_t acl" "acl_entry_t entry_d" .Sh DESCRIPTION +The .Fn acl_delete_entry +function is a POSIX.1e call that removes the ACL entry .Fa entry_d from ACL diff --git a/lib/libc/posix1e/acl_delete_perm.3 b/lib/libc/posix1e/acl_delete_perm.3 index 3f8d27b..a3343aa0 100644 --- a/lib/libc/posix1e/acl_delete_perm.3 +++ b/lib/libc/posix1e/acl_delete_perm.3 @@ -39,7 +39,9 @@ .Ft int .Fn acl_delete_perm "acl_permset_t permset_d" "acl_perm_t perm" .Sh DESCRIPTION +The .Fn acl_delete_perm +function is a POSIX.1e call that removes specific permissions from permissions set .Fa perm . .Sh RETURN VALUES diff --git a/lib/libc/posix1e/acl_from_text.3 b/lib/libc/posix1e/acl_from_text.3 index 25e8597..48adc03 100644 --- a/lib/libc/posix1e/acl_from_text.3 +++ b/lib/libc/posix1e/acl_from_text.3 @@ -103,9 +103,11 @@ and development continues. .Sh BUGS These features are not yet fully implemented. .Pp +The .Fn acl_from_text and .Fn acl_to_text +functions rely on the .Xr getpwent 3 library calls to manage username and uid mapping, as well as the diff --git a/lib/libc/posix1e/acl_get.3 b/lib/libc/posix1e/acl_get.3 index c1dd5b5..4ca86b5 100644 --- a/lib/libc/posix1e/acl_get.3 +++ b/lib/libc/posix1e/acl_get.3 @@ -51,14 +51,18 @@ The and .Fn acl_get_fd_np each allow the retrieval of an ACL from a file. +The .Fn acl_get_file +function is a POSIX.1e call that allows the retrieval of a specified type of ACL from a file by name; .Fn acl_get_fd is a POSIX.1e call that allows the retrieval of an ACL of type ACL_TYPE_ACCESS from a file descriptor. +The .Fn acl_get_fd_np +function is a non-portable form of .Fn acl_get_fd that allows the retrieval of any type of ACL from a file descriptor. diff --git a/lib/libc/posix1e/acl_get_entry.3 b/lib/libc/posix1e/acl_get_entry.3 index 94e2321..528fd34 100644 --- a/lib/libc/posix1e/acl_get_entry.3 +++ b/lib/libc/posix1e/acl_get_entry.3 @@ -39,7 +39,9 @@ .Ft int .Fn acl_get_entry "acl_t acl" "int entry_id" "acl_entry_t *entry_p" .Sh DESCRIPTION +The .Fn acl_get_entry +function is a POSIX.1e call that retrieves a descriptor for an ACL entry specified by the argument .Fa entry_d diff --git a/lib/libc/posix1e/acl_get_perm_np.3 b/lib/libc/posix1e/acl_get_perm_np.3 index 44477f2..7fe6c9c 100644 --- a/lib/libc/posix1e/acl_get_perm_np.3 +++ b/lib/libc/posix1e/acl_get_perm_np.3 @@ -39,7 +39,9 @@ .Ft int .Fn acl_get_perm_np "acl_permset_t permset_d" "acl_perm_t perm" .Sh DESCRIPTION +The .Fn acl_get_perm_np +function is a non-portable function that checks if a permission is set in a permission set. .Sh RETURN VALUES diff --git a/lib/libc/posix1e/acl_get_permset.3 b/lib/libc/posix1e/acl_get_permset.3 index 293b600..403b10a 100644 --- a/lib/libc/posix1e/acl_get_permset.3 +++ b/lib/libc/posix1e/acl_get_permset.3 @@ -39,7 +39,9 @@ .Ft int .Fn acl_get_permset "acl_entry_t entry_d" "acl_permset_t *permset_p" .Sh DESCRIPTION +The .Fn acl_get_permset +function is a POSIX.1e call that returns via .Fa permset_p a descriptor to the permission set in the ACL entry diff --git a/lib/libc/posix1e/acl_get_qualifier.3 b/lib/libc/posix1e/acl_get_qualifier.3 index be5df9b..a670ddb 100644 --- a/lib/libc/posix1e/acl_get_qualifier.3 +++ b/lib/libc/posix1e/acl_get_qualifier.3 @@ -39,7 +39,9 @@ .Ft void * .Fn acl_get_qualifier "acl_entry_t entry_d" .Sh DESCRIPTION +The .Fn acl_get_qualifier +function is a POSIX.1e call that retrieves the qualifier of the tag for the ACL entry indicated by the argument .Fa entry_d diff --git a/lib/libc/posix1e/acl_get_tag_type.3 b/lib/libc/posix1e/acl_get_tag_type.3 index daf593c..e84ad49 100644 --- a/lib/libc/posix1e/acl_get_tag_type.3 +++ b/lib/libc/posix1e/acl_get_tag_type.3 @@ -39,7 +39,9 @@ .Ft int .Fn acl_get_tag_type "acl_entry_t entry_d" "acl_tag_t *tag_type_p" .Sh DESCRIPTION +The .Fn acl_get_tag_type +function is a POSIX.1e call that returs the tag type for the ACL entry .Fa entry_d . Upon successful completion, the location referred to by the argument diff --git a/lib/libc/posix1e/acl_set_permset.3 b/lib/libc/posix1e/acl_set_permset.3 index a4d8bfe..152e226 100644 --- a/lib/libc/posix1e/acl_set_permset.3 +++ b/lib/libc/posix1e/acl_set_permset.3 @@ -39,7 +39,9 @@ .Ft int .Fn acl_set_permset "acl_entry_t entry_d" "acl_permset_t permset_d" .Sh DESCRIPTION +The .Fn acl_set_permset +function is a POSIX.1e call that sets the permissions of ACL entry .Fa entry_d with the permissions contained in diff --git a/lib/libc/posix1e/acl_set_qualifier.3 b/lib/libc/posix1e/acl_set_qualifier.3 index abc77d9..04dc2a2 100644 --- a/lib/libc/posix1e/acl_set_qualifier.3 +++ b/lib/libc/posix1e/acl_set_qualifier.3 @@ -39,7 +39,9 @@ .Ft int .Fn acl_set_qualifier "acl_entry_t entry_d" "const void *tag_qualifier_p" .Sh DESCRIPTION +The .Fn acl_set_qualifier +function is a POSIX.1e call that sets the qualifier of the tag for the ACl entry .Fa entry_d to the value referred to by diff --git a/lib/libc/posix1e/acl_set_tag_type.3 b/lib/libc/posix1e/acl_set_tag_type.3 index 57ce397..460e925 100644 --- a/lib/libc/posix1e/acl_set_tag_type.3 +++ b/lib/libc/posix1e/acl_set_tag_type.3 @@ -39,7 +39,9 @@ .Ft int .Fn acl_set_tag_type "acl_entry_t entry_d" "acl_tag_t tag_type" .Sh DESCRIPTION +The .Fn acl_set_tag_type +function is a POSIX.1e call that sets the ACL tag type of ACL entry .Fa entry_d to the value of diff --git a/lib/libc/posix1e/acl_to_text.3 b/lib/libc/posix1e/acl_to_text.3 index 93a05ee..8da6d9d 100644 --- a/lib/libc/posix1e/acl_to_text.3 +++ b/lib/libc/posix1e/acl_to_text.3 @@ -113,9 +113,11 @@ and development continues. .Sh BUGS These features are not yet fully implemented. .Pp +The .Fn acl_from_text and .Fn acl_to_text +functions rely on the .Xr getpwent 3 library calls to manage username and uid mapping, as well as the diff --git a/lib/libc/regex/regex.3 b/lib/libc/regex/regex.3 index dc0bac8..22e8447 100644 --- a/lib/libc/regex/regex.3 +++ b/lib/libc/regex/regex.3 @@ -72,7 +72,9 @@ regular expressions .Pq Do RE Dc Ns s ; see .Xr re_format 7 . -.Fn Regcomp +The +.Fn regcomp +function compiles an RE written as a string into an internal form, .Fn regexec matches that internal form against a string and reports results, @@ -96,7 +98,9 @@ a type and a number of constants with names starting with .Dq Dv REG_ . .Pp -.Fn Regcomp +The +.Fn regcomp +function compiles the regular expression contained in the .Fa pattern string, @@ -204,7 +208,9 @@ fails, it returns a non-zero error code; see .Sx DIAGNOSTICS . .Pp -.Fn Regexec +The +.Fn regexec +function matches the compiled RE pointed to by .Fa preg against the @@ -390,7 +396,9 @@ the value of will not be changed by a successful .Fn regexec . .Pp -.Fn Regerror +The +.Fn regerror +function maps a non-zero .Fa errcode from either @@ -413,11 +421,14 @@ it should have been the result from the most recent .Fn regcomp using that .Ft regex_t . -.No ( Fn Regerror +The +.Fn ( regerror may be able to supply a more detailed message using information from the .Ft regex_t . ) -.Fn Regerror +The +.Fn regerror +function places the NUL-terminated message into the buffer pointed to by .Fa errbuf , limiting the length (including the NUL) to at most @@ -474,7 +485,9 @@ and should be used with caution in software intended to be portable to other systems. Be warned also that they are considered experimental and changes are possible. .Pp -.Fn Regfree +The +.Fn regfree +function frees any dynamically-allocated storage associated with the compiled RE pointed to by .Fa preg . @@ -590,7 +603,9 @@ include the following: .Pp .Bl -tag -width REG_ECOLLATE -compact .It Dv REG_NOMATCH +The .Fn regexec +function failed to match .It Dv REG_BADPAT invalid regular expression @@ -649,14 +664,18 @@ Please report problems. The back-reference code is subtle and doubts linger about its correctness in complex cases. .Pp -.Fn Regexec +The +.Fn regexec +function performance is poor. This will improve with later releases. .Fa Nmatch exceeding 0 is expensive; .Fa nmatch exceeding 1 is worse. -.Fn Regexec +The +.Fn regexec +function is largely insensitive to RE complexity .Em except that back @@ -665,7 +684,9 @@ RE length does matter; in particular, there is a strong speed bonus for keeping RE length under about 30 characters, with most special characters counting roughly double. .Pp -.Fn Regcomp +The +.Fn regcomp +function implements bounded repetitions by macro expansion, which is costly in time and space if counts are large or bounded repetitions are nested. diff --git a/lib/libc/rpc/bindresvport.3 b/lib/libc/rpc/bindresvport.3 index 740dd15..28e86e5 100644 --- a/lib/libc/rpc/bindresvport.3 +++ b/lib/libc/rpc/bindresvport.3 @@ -19,9 +19,11 @@ .Ft int .Fn bindresvport_sa "int sd" "struct sockaddr *sa" .Sh DESCRIPTION +The .Fn bindresvport and .Fn bindresvport_sa +functions are used to bind a socket descriptor to a privileged .Tn IP port, that is, a @@ -65,7 +67,9 @@ Function prototype of is biased to .Dv AF_INET socket. +The .Fn bindresvport_sa +function acts exactly the same, with more neutral function prototype. Note that both functions behave exactly the same, and both support @@ -82,7 +86,9 @@ If second argument was supplied, and address family did not match between arguments. .El .Pp +The .Fn bindresvport +function may also fail and set .Va errno for any of the errors specified for the calls diff --git a/lib/libc/rpc/des_crypt.3 b/lib/libc/rpc/des_crypt.3 index 0655d56..39b927b 100644 --- a/lib/libc/rpc/des_crypt.3 +++ b/lib/libc/rpc/des_crypt.3 @@ -18,9 +18,11 @@ .Ft void .Fn des_setparity "char *key" .Sh DESCRIPTION +The .Fn ecb_crypt and .Fn cbc_crypt +functions implement the .Tn NBS .Tn DES @@ -30,12 +32,16 @@ These routines are faster and more general purpose than They also are able to utilize .Tn DES hardware if it is available. +The .Fn ecb_crypt +function encrypts in .Tn ECB (Electronic Code Book) mode, which encrypts blocks of data independently. +The .Fn cbc_crypt +function encrypts in .Tn CBC (Cipher Block Chaining) diff --git a/lib/libc/rpc/getnetconfig.3 b/lib/libc/rpc/getnetconfig.3 index 74a4a21..241b946 100644 --- a/lib/libc/rpc/getnetconfig.3 +++ b/lib/libc/rpc/getnetconfig.3 @@ -37,7 +37,9 @@ The library routines described on this page provide the application access to the system network configuration database, .Pa /etc/netconfig . +The .Fn getnetconfig +function returns a pointer to the current entry in the netconfig @@ -45,10 +47,14 @@ database, formatted as a .Ft "struct netconfig" . Successive calls will return successive netconfig entries in the netconfig database. +The .Fn getnetconfig +function can be used to search the entire netconfig file. +The .Fn getnetconfig +function returns .Dv NULL at the end of the file. @@ -63,18 +69,26 @@ has the effect of to or .Dq rewinding the netconfig database. +The .Fn setnetconfig +function must be called before the first call to .Fn getnetconfig and may be called at any other time. +The .Fn setnetconfig +function need not be called before a call to .Fn getnetconfigent . +The .Fn setnetconfig +function returns a unique handle to be used by .Fn getnetconfig . .Pp +The .Fn endnetconfig +function should be called when processing is complete to release resources for reuse. .Fa handlep is the handle obtained through @@ -86,11 +100,15 @@ frees all memory allocated by for the .Ft "struct netconfig" data structure. +The .Fn endnetconfig +function may not be called before .Fn setnetconfig . .Pp +The .Fn getnetconfigent +function returns a pointer to the netconfig structure corresponding to @@ -102,13 +120,17 @@ if is invalid (that is, does not name an entry in the netconfig database). .Pp +The .Fn freenetconfigent +function frees the netconfig structure pointed to by .Fa netconfigp (previously returned by .Fn getnetconfigent ) . .Pp +The .Fn nc_perror +function prints a message to the standard error indicating why any of the above routines failed. The message is prepended with the string @@ -116,22 +138,28 @@ The message is prepended with the string and a colon. A newline character is appended at the end of the message. .Pp +The .Fn nc_sperror +function is similar to .Fn nc_perror but instead of sending the message to the standard error, will return a pointer to a string that contains the error message. .Pp +The .Fn nc_perror and .Fn nc_sperror +functions can also be used with the .Ev NETPATH access routines defined in .Xr getnetpath 3 . .Sh RETURN VALUES +The .Fn setnetconfig +function returns a unique handle to be used by .Fn getnetconfig . In the case of an error, @@ -144,16 +172,22 @@ or .Fn nc_sperror can be used to print the reason for failure. .Pp +The .Fn getnetconfig +function returns a pointer to the current entry in the netconfig database, formatted as a .Ft "struct netconfig" . +The .Fn getnetconfig +function returns .Dv NULL at the end of the file, or upon failure. .Pp +The .Fn endnetconfig +function returns 0 on success and \-1 on failure (for example, if .Fn setnetconfig @@ -168,7 +202,9 @@ structure corresponding to otherwise it returns .Dv NULL . .Pp +The .Fn nc_sperror +function returns a pointer to a buffer which contains the error message string. This buffer is overwritten on each call. In multithreaded applications, this buffer is diff --git a/lib/libc/rpc/getnetpath.3 b/lib/libc/rpc/getnetpath.3 index f2d7358..5dfe68a 100644 --- a/lib/libc/rpc/getnetpath.3 +++ b/lib/libc/rpc/getnetpath.3 @@ -42,7 +42,9 @@ The .Ev NETPATH variable is a list of colon-separated network identifiers. .Pp +The .Fn getnetpath +function returns a pointer to the netconfig database entry corresponding to the first valid .Ev NETPATH @@ -55,7 +57,9 @@ returns a pointer to the netconfig entry that corresponds to the next valid .Ev NETPATH component. +The .Fn getnetpath +function can thus be used to search the netconfig database for all networks included in the .Ev NETPATH @@ -73,14 +77,18 @@ A call to to or .Dq rewinds .Ev NETPATH . +The .Fn setnetpath +function must be called before the first call to .Fn getnetpath and may be called at any other time. It returns a handle that is used by .Fn getnetpath . .Pp +The .Fn getnetpath +function silently ignores invalid .Ev NETPATH components. @@ -104,7 +112,9 @@ order in which they are listed. .\"This proviso holds also for this .\"whole manpage. .Pp +The .Fn endnetpath +function may be called to .Dq unbind from @@ -116,7 +126,9 @@ frees all memory allocated by .Fn getnetpath for the struct netconfig data structure. .Sh RETURN VALUES +The .Fn setnetpath +function returns a handle that is used by .Fn getnetpath . In case of an error, @@ -124,14 +136,18 @@ In case of an error, returns .Dv NULL . .Pp +The .Fn endnetpath +function returns 0 on success and \-1 on failure (for example, if .Fn setnetpath was not called previously). +The .Fn nc_perror or .Fn nc_sperror +function can be used to print out the reason for failure. See .Xr getnetconfig 3 . diff --git a/lib/libc/rpc/getrpcent.3 b/lib/libc/rpc/getrpcent.3 index 190bf8a..862a89f 100644 --- a/lib/libc/rpc/getrpcent.3 +++ b/lib/libc/rpc/getrpcent.3 @@ -27,10 +27,12 @@ .Ft void .Fn endrpcent void .Sh DESCRIPTION +The .Fn getrpcent , .Fn getrpcbyname , and .Fn getrpcbynumber +functions each return a pointer to an object with the following structure containing the broken-out @@ -54,10 +56,14 @@ A zero terminated list of alternate names for the rpc program. The rpc program number for this service. .El .Pp +The .Fn getrpcent +function reads the next line of the file, opening the file if necessary. .Pp +The .Fn setrpcent +function opens and rewinds the file. If the .Fa stayopen flag is non-zero, @@ -68,12 +74,16 @@ the other .Dq getrpc calls). .Pp +The .Fn endrpcent +function closes the file. .Pp +The .Fn getrpcbyname and .Fn getrpcbynumber +functions sequentially search from the beginning of the file until a matching rpc program name or program number is found, or until end-of-file is encountered. diff --git a/lib/libc/rpc/getrpcport.3 b/lib/libc/rpc/getrpcport.3 index 3b67685..13985b4 100644 --- a/lib/libc/rpc/getrpcport.3 +++ b/lib/libc/rpc/getrpcport.3 @@ -13,7 +13,9 @@ .Ft int .Fn getrpcport "char *host" "int prognum" "int versnum" "int proto" .Sh DESCRIPTION +The .Fn getrpcport +function returns the port number for version .Fa versnum of the RPC program diff --git a/lib/libc/rpc/publickey.3 b/lib/libc/rpc/publickey.3 index 6a46c9a..369ae8b 100644 --- a/lib/libc/rpc/publickey.3 +++ b/lib/libc/rpc/publickey.3 @@ -27,7 +27,9 @@ These routines are used to get public and secret keys from the .Tn YP database. +The .Fn getsecretkey +function has an extra argument, .Fa passwd , which is used to decrypt the encrypted secret key stored in the database. diff --git a/lib/libc/rpc/rpc_clnt_calls.3 b/lib/libc/rpc/rpc_clnt_calls.3 index 126efce..08435b8 100644 --- a/lib/libc/rpc/rpc_clnt_calls.3 +++ b/lib/libc/rpc/rpc_clnt_calls.3 @@ -166,7 +166,9 @@ Take the same arguments as but instead of sending a message to the standard error indicating why an RPC call failed, return a pointer to a string which contains the message. +The .Fn clnt_sperrno +function is normally used instead of .Fn clnt_perrno when the program does not have a standard error (as a program @@ -240,7 +242,9 @@ Warning: broadcast file descriptors are limited in size to the maximum transfer size of that transport. For Ethernet, this value is 1500 bytes. +The .Fn rpc_broadcast +function uses .Dv AUTH_SYS credentials by default (see diff --git a/lib/libc/rpc/rpc_clnt_create.3 b/lib/libc/rpc/rpc_clnt_create.3 index e6e9636..ca6f92e 100644 --- a/lib/libc/rpc/rpc_clnt_create.3 +++ b/lib/libc/rpc/rpc_clnt_create.3 @@ -119,7 +119,9 @@ The following operations are valid for connectionless transports only: .Pp The retry timeout is the time that RPC waits for the server to reply before retransmitting the request. +The .Fn clnt_control +function returns .Dv TRUE on success and @@ -139,7 +141,9 @@ The transports are tried in left to right order in .Ev NETPATH environment variable or in top to bottom order in the netconfig database. +The .Fn clnt_create +function tries all the transports of the .Fa nettype class available from the @@ -336,7 +340,9 @@ without any kernel or networking interference. This routine returns .Dv NULL if it fails. +The .Fn clnt_raw_create +function should be called after .Fn svc_raw_create . .It Fn clnt_tli_create @@ -406,7 +412,9 @@ except .Fn clnt_tp_create tries only one transport specified through .Fa netconf . +The .Fn clnt_tp_create +function creates a client handle for the program .Fa prognum , the version @@ -466,7 +474,9 @@ The address should not be .Dv NULL and should point to the actual address of the remote program. +The .Fn clnt_vc_create +function does not consult the remote rpcbind service for this information. .It Xo .Vt "struct rpc_createerr" Va rpc_createerr ; diff --git a/lib/libc/rpc/rpc_secure.3 b/lib/libc/rpc/rpc_secure.3 index e90f7e4..27b9870 100644 --- a/lib/libc/rpc/rpc_secure.3 +++ b/lib/libc/rpc/rpc_secure.3 @@ -63,7 +63,9 @@ must be running for the .Tn DES authentication system to work. .Pp -.Fn Authdes_create , +The +.Fn authdes_create +function, used on the client side, returns an authentication handle that will enable the use of the secure authentication system. The first parameter @@ -110,7 +112,9 @@ generate a random key to be used for the encryption of credentials. If it is supplied, however, then it will be used instead. .Pp -.Fn Authdes_getucred , +The +.Fn authdes_getucred +function, the second of the two .Tn DES authentication routines, @@ -127,7 +131,9 @@ in that pulls its information from a cache, and does not have to do a Yellow Pages lookup every time it is called to get its information. .Pp -.Fn Getnetname +The +.Fn getnetname +function installs the unique, operating-system independent netname of the caller in the fixed-length array @@ -138,7 +144,9 @@ if it succeeds and .Dv FALSE if it fails. .Pp -.Fn Host2netname +The +.Fn host2netname +function converts from a domain-specific hostname to an operating-system independent netname. Returns @@ -149,7 +157,9 @@ if it fails. Inverse of .Fn netname2host . .Pp -.Fn Key_decryptsession +The +.Fn key_decryptsession +function is an interface to the keyserver daemon, which is associated with .Tn RPC Ns 's @@ -167,7 +177,9 @@ and the .Tn RPC library are the main clients of these four routines. .Pp -.Fn Key_decryptsession +The +.Fn key_decryptsession +function takes a server netname and a .Tn DES key, and decrypts the key by @@ -176,7 +188,9 @@ associated with the effective uid of the calling process. It is the inverse of .Fn key_encryptsession . .Pp -.Fn Key_encryptsession +The +.Fn key_encryptsession +function is a keyserver interface routine. It takes a server netname and a des key, and encrypts @@ -185,7 +199,9 @@ associated with the effective uid of the calling process. It is the inverse of .Fn key_decryptsession . .Pp -.Fn Key_gendes +The +.Fn key_gendes +function is a keyserver interface routine. It is used to ask the keyserver for a secure conversation key. @@ -196,14 +212,18 @@ because the common ways of choosing random numbers, such as using the current time, are very easy to guess. .Pp -.Fn Key_setsecret +The +.Fn key_setsecret +function is a keyserver interface routine. It is used to set the key for the effective .Fa uid of the calling process. .Pp -.Fn Netname2host +The +.Fn netname2host +function converts from an operating-system independent netname to a domain-specific hostname. Returns @@ -213,7 +233,9 @@ if it succeeds and if it fails. Inverse of .Fn host2netname . .Pp -.Fn Netname2user +The +.Fn netname2user +function converts from an operating-system independent netname to a domain-specific user ID. Returns @@ -224,7 +246,9 @@ if it fails. Inverse of .Fn user2netname . .Pp -.Fn User2netname +The +.Fn user2netname +function converts from a domain-specific username to an operating-system independent netname. Returns diff --git a/lib/libc/rpc/rpc_soc.3 b/lib/libc/rpc/rpc_soc.3 index 14a5462..5bf4099 100644 --- a/lib/libc/rpc/rpc_soc.3 +++ b/lib/libc/rpc/rpc_soc.3 @@ -538,7 +538,9 @@ indicating why an call failed, return a pointer to a string which contains the message. .Pp +The .Fn clnt_sperrno +function is used instead of .Fn clnt_perrno if the program does not have a standard error (as a program diff --git a/lib/libc/rpc/rpc_svc_calls.3 b/lib/libc/rpc/rpc_svc_calls.3 index 78d98ec..82b82aa 100644 --- a/lib/libc/rpc/rpc_svc_calls.3 +++ b/lib/libc/rpc/rpc_svc_calls.3 @@ -103,7 +103,9 @@ either through one of the .Xr rpc_svc_create 3 functions, or using .Fn xprt_register . +The .Fn svc_exit +function has global scope and ends all RPC server activity. .It Xo .Vt fd_set Va svc_fdset diff --git a/lib/libc/rpc/rpc_svc_create.3 b/lib/libc/rpc/rpc_svc_create.3 index ccc6544..23c0053 100644 --- a/lib/libc/rpc/rpc_svc_create.3 +++ b/lib/libc/rpc/rpc_svc_create.3 @@ -108,7 +108,9 @@ or 1 (indicating that the out of range request should be silently ignored). .El .It Fn svc_create +The .Fn svc_create +function creates server handles for all the transports belonging to the class .Fa nettype . @@ -125,7 +127,9 @@ is it defaults to .Qq netpath . .Pp +The .Fn svc_create +function registers itself with the rpcbind service (see .Xr rpcbind 8 ) . @@ -266,7 +270,9 @@ The server is not registered with the .Xr rpcbind 8 service. .It Fn svc_tp_create +The .Fn svc_tp_create +function creates a server handle for the network specified by .Fa netconf , @@ -279,7 +285,9 @@ and .Fa versnum ; this requires calling .Fn svc_run . +The .Fn svc_tp_create +function returns the service handle if it succeeds, otherwise a .Dv NULL diff --git a/lib/libc/rpc/rpcbind.3 b/lib/libc/rpc/rpcbind.3 index eec41b7..d9ccaaf 100644 --- a/lib/libc/rpc/rpcbind.3 +++ b/lib/libc/rpc/rpcbind.3 @@ -97,7 +97,9 @@ This routine returns if it succeeds, .Dv FALSE if it fails. +The .Fn rpcb_gettime +function can be used to synchronize the time between the client and the remote server. .It Fn rpcb_rmtcall diff --git a/lib/libc/rpc/rtime.3 b/lib/libc/rpc/rtime.3 index d402c26..5e85e9c 100644 --- a/lib/libc/rpc/rtime.3 +++ b/lib/libc/rpc/rtime.3 @@ -20,7 +20,9 @@ .Fa "struct timeval *timeout" .Fc .Sh DESCRIPTION +The .Fn rtime +function consults the Internet Time Server at the address pointed to by .Fa addrp and returns the remote time in the diff --git a/lib/libc/stdio/fclose.3 b/lib/libc/stdio/fclose.3 index 6d71811..9d48228 100644 --- a/lib/libc/stdio/fclose.3 +++ b/lib/libc/stdio/fclose.3 @@ -77,7 +77,9 @@ for any of the errors specified for the routines or .Xr fflush 3 . .Sh NOTES +The .Fn fclose +function does not handle NULL arguments; they will result in a segmentation violation. This is intentional - it makes it easier to make sure programs written diff --git a/lib/libc/stdio/fwide.3 b/lib/libc/stdio/fwide.3 index 983e9b7..6ff8d92 100644 --- a/lib/libc/stdio/fwide.3 +++ b/lib/libc/stdio/fwide.3 @@ -73,7 +73,9 @@ is zero, and .Fa stream is unchanged. .Sh RETURN VALUES +The .Fn fwide +function returns a value according to orientation after the call of .Fn fwide ; a value less than zero if byte-oriented, a value greater than zero diff --git a/lib/libc/stdio/mktemp.3 b/lib/libc/stdio/mktemp.3 index 06fe894..5c9de2e 100644 --- a/lib/libc/stdio/mktemp.3 +++ b/lib/libc/stdio/mktemp.3 @@ -94,7 +94,9 @@ function acts the same as except it permits a suffix to exist in the template. The template should be of the form .Pa /tmp/tmpXXXXXXsuffix . +The .Fn mkstemps +function is told the length of the suffix string. .Pp The diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3 index 3f8e640..f5848dd 100644 --- a/lib/libc/stdio/printf.3 +++ b/lib/libc/stdio/printf.3 @@ -74,9 +74,11 @@ The family of functions produces output according to a .Fa format as described below. -.Fn Printf +The +.Fn printf and .Fn vprintf +functions write output to .Dv stdout , the standard output stream; @@ -120,9 +122,11 @@ were unlimited (again, not including the final .Ql \e0 ) . .Pp -.Fn Asprintf +The +.Fn asprintf and .Fn vasprintf +functions set .Fa *ret to be a pointer to a buffer sufficiently large to hold the formatted string. @@ -139,9 +143,11 @@ to be a .Dv NULL pointer. .Pp -.Fn Snprintf +The +.Fn snprintf and .Fn vsnprintf +functions will write at most .Fa size Ns \-1 of the characters printed into the output string @@ -155,9 +161,11 @@ argument, the string was too short and some of the printed characters were discarded. The output is always null-terminated. .Pp -.Fn Sprintf +The +.Fn sprintf and .Fn vsprintf +functions effectively assume an infinite .Fa size . .Pp diff --git a/lib/libc/stdio/tmpnam.3 b/lib/libc/stdio/tmpnam.3 index 9f8c18d..fd22bea 100644 --- a/lib/libc/stdio/tmpnam.3 +++ b/lib/libc/stdio/tmpnam.3 @@ -132,7 +132,9 @@ if .Pf non- Dv NULL , is used to specify a file name prefix, which will be the first part of the created file name. -.Fn Tempnam +The +.Fn tempnam +function allocates memory in which to store the file name; the returned pointer may be used as a subsequent argument to .Xr free 3 . diff --git a/lib/libc/stdlib/getopt_long.3 b/lib/libc/stdlib/getopt_long.3 index fa15076..9f46bff 100644 --- a/lib/libc/stdlib/getopt_long.3 +++ b/lib/libc/stdlib/getopt_long.3 @@ -59,7 +59,9 @@ The .Fn getopt_long function provides a superset of the functionality of .Xr getopt 3 . +The .Fn getopt_long +function can be used in two ways. In the first way, every long option understood by the program has a corresponding short option, and the option diff --git a/lib/libc/stdlib/lsearch.3 b/lib/libc/stdlib/lsearch.3 index 453d297..4eecb1e 100644 --- a/lib/libc/stdlib/lsearch.3 +++ b/lib/libc/stdlib/lsearch.3 @@ -64,9 +64,11 @@ into the position after the last element and increments the integer pointed to by .Fa nelp . .Sh RETURN VALUES +The .Fn lsearch and .Fn lfind +functions return a pointer to the first element found. If no element was found, .Fn lsearch diff --git a/lib/libc/stdlib/malloc.3 b/lib/libc/stdlib/malloc.3 index 376b42d..6c11ea7 100644 --- a/lib/libc/stdlib/malloc.3 +++ b/lib/libc/stdlib/malloc.3 @@ -135,7 +135,9 @@ for the specified size. .Pp The .Fn reallocf -function call is identical to the realloc function call, except that it +function is identical to the +.Fn realloc +function, except that it will free the passed pointer when the requested memory cannot be allocated. This is a .Fx diff --git a/lib/libc/stdlib/qsort.3 b/lib/libc/stdlib/qsort.3 index a23301f..a734da2 100644 --- a/lib/libc/stdlib/qsort.3 +++ b/lib/libc/stdlib/qsort.3 @@ -97,7 +97,9 @@ objects, the initial member of which is pointed to by .Fa base . The size of each object is specified by .Fa size . -.Fn Mergesort +The +.Fn mergesort +function behaves similarly, but .Em requires that @@ -179,7 +181,9 @@ requires additional memory of size .Fa nmemb * .Fa size bytes; it should be used only when space is not at a premium. -.Fn Mergesort +The +.Fn mergesort +function is optimized for data with pre-existing order; its worst case time is O N lg N; its best case is O N. .Pp @@ -218,9 +222,11 @@ argument to is less than .Dq "sizeof(void *) / 2" . .It Bq Er ENOMEM -.Fn Heapsort +The +.Fn heapsort or .Fn mergesort +functions were unable to allocate memory. .El .Sh COMPATIBILITY diff --git a/lib/libc/stdlib/rand.3 b/lib/libc/stdlib/rand.3 index e7d3aaf..513a9f6 100644 --- a/lib/libc/stdlib/rand.3 +++ b/lib/libc/stdlib/rand.3 @@ -94,7 +94,9 @@ function initializes a seed using the random number device which returns good random numbers, suitable for cryptographic use. .Pp +The .Fn rand_r +function provides the same functionality as .Fn rand . A pointer to the context value diff --git a/lib/libc/stdlib/realpath.3 b/lib/libc/stdlib/realpath.3 index 9479a3c..2351c8f 100644 --- a/lib/libc/stdlib/realpath.3 +++ b/lib/libc/stdlib/realpath.3 @@ -124,5 +124,5 @@ when given a relative .Sh HISTORY The .Fn realpath -function call first appeared in +function first appeared in .Bx 4.4 . diff --git a/lib/libc/stdlib/tsearch.3 b/lib/libc/stdlib/tsearch.3 index cfe39c2..ac6d841 100644 --- a/lib/libc/stdlib/tsearch.3 +++ b/lib/libc/stdlib/tsearch.3 @@ -55,7 +55,9 @@ from Knuth (6.2.2). The comparison function passed in by the user has the same style of return values as .Xr strcmp 3 . .Pp -.Fn Tfind +The +.Fn tfind +function searches for the datum matched by the argument .Fa key in the binary tree rooted at @@ -63,7 +65,9 @@ in the binary tree rooted at returning a pointer to the datum if it is found and NULL if it is not. .Pp -.Fn Tsearch +The +.Fn tsearch +function is identical to .Fn tfind except that if no match is found, @@ -72,7 +76,9 @@ is inserted into the tree and a pointer to it is returned. If .Fa rootp points to a NULL value a new binary search tree is created. .Pp -.Fn Tdelete +The +.Fn tdelete +function deletes a node from the specified binary search tree and returns a pointer to the parent of the node to be deleted. It takes the same arguments as @@ -83,7 +89,9 @@ If the node to be deleted is the root of the binary search tree, .Fa rootp will be adjusted. .Pp -.Fn Twalk +The +.Fn twalk +function walks the binary search tree rooted in .Fa root and calls the function @@ -105,10 +113,12 @@ The function returns NULL if allocation of a new node fails (usually due to a lack of free memory). .Pp -.Fn Tfind , +The +.Fn tfind , .Fn tsearch , and .Fn tdelete +functions return NULL if .Fa rootp is NULL or the datum cannot be found. diff --git a/lib/libc/stdtime/ctime.3 b/lib/libc/stdtime/ctime.3 index d970e4f..63c3408 100644 --- a/lib/libc/stdtime/ctime.3 +++ b/lib/libc/stdtime/ctime.3 @@ -140,15 +140,19 @@ Thu Nov 24 18:22:48 1986\en\e0 .Pp All the fields have constant width. .Pp +The .Fn ctime_r +function provides the same functionality as .Fn ctime except the caller must provide the output buffer .Fa buf to store the result, which must be at least 26 characters long. +The .Fn localtime_r and .Fn gmtime_r +functions provide the same functionality as .Fn localtime and @@ -166,7 +170,9 @@ pointed at by to the form shown in the example above. .Pp +The .Fn asctime_r +function provides the same functionality as .Fn asctime except the caller provide the output buffer @@ -183,11 +189,15 @@ values returned by the .Xr time 3 function (that is, seconds from the Epoch, .Tn UTC ) . +The .Fn mktime +function interprets the input structure according to the current timezone setting (see .Xr tzset 3 ) . +The .Fn timegm +function interprets the input structure as representing Universal Coordinated Time .Pq Tn UTC . .Pp @@ -240,7 +250,9 @@ is not set until and .Fa tm_year are determined. -.Fn Mktime +The +.Fn mktime +function returns the specified calendar time; if the calendar time cannot be represented, it returns \-1; .Pp diff --git a/lib/libc/string/strcpy.3 b/lib/libc/string/strcpy.3 index d52d0ed..1ee2beb 100644 --- a/lib/libc/string/strcpy.3 +++ b/lib/libc/string/strcpy.3 @@ -195,7 +195,9 @@ conform to The .Fn stpcpy function is an MS-DOS and GNUism. +The .Fn stpcpy +function conforms to no standard. .Sh HISTORY The diff --git a/lib/libc/string/strlcpy.3 b/lib/libc/string/strlcpy.3 index 55a6a41..3cc5ae4 100644 --- a/lib/libc/string/strlcpy.3 +++ b/lib/libc/string/strlcpy.3 @@ -192,6 +192,7 @@ As a matter of fact, the first version of this manual page got it wrong. .Xr strncat 3 , .Xr strncpy 3 .Sh HISTORY +The .Fn strlcpy and .Fn strlcat diff --git a/lib/libc/string/strtok.3 b/lib/libc/string/strtok.3 index 9067a0a..ba47f72 100644 --- a/lib/libc/string/strtok.3 +++ b/lib/libc/string/strtok.3 @@ -98,7 +98,9 @@ function is a reentrant version of The context pointer .Fa last must be provided on each call. +The .Fn strtok_r +function may also be used to nest two parsing loops within one another, as long as separate context pointers are used. .Pp diff --git a/lib/libc/xdr/xdr.3 b/lib/libc/xdr/xdr.3 index 1b105e5..fbaf61e 100644 --- a/lib/libc/xdr/xdr.3 +++ b/lib/libc/xdr/xdr.3 @@ -793,7 +793,9 @@ A primitive that calls where .Dv MAXUN.UNSIGNED is the maximum value of an unsigned integer. +The .Fn xdr_wrapstring +function is handy because the .Tn RPC package passes a maximum of two -- cgit v1.1