From 0552350ecc55f34e3385dc06abf3c9c45092b332 Mon Sep 17 00:00:00 2001 From: Philippe Charnier Date: Mon, 24 Mar 2003 16:02:05 +0000 Subject: [PATCH] The .Fn function --- lib/libcompat/4.1/cftime.3 | 12 +++++++----- lib/libcompat/4.4/cuserid.3 | 3 ++- lib/libipsec/ipsec_set_policy.3 | 6 ++++-- lib/libmd/mdX.3 | 15 ++++++++++----- lib/libmd/ripemd.3 | 12 ++++++++---- lib/libutil/_secure_path.3 | 3 ++- lib/libutil/login_cap.3 | 6 ++++-- lib/libutil/login_class.3 | 12 +++++++----- lib/libutil/login_ok.3 | 6 ++++-- lib/libutil/login_times.3 | 12 ++++++++---- lib/libutil/login_tty.3 | 5 +++-- lib/libutil/logout.3 | 5 +++-- lib/libutil/property.3 | 6 ++++-- lib/libutil/pty.3 | 17 ++++++++++------- lib/libutil/realhostname.3 | 3 ++- lib/libutil/realhostname_sa.3 | 3 ++- lib/libutil/trimdomain.3 | 6 ++++-- 17 files changed, 84 insertions(+), 48 deletions(-) diff --git a/lib/libcompat/4.1/cftime.3 b/lib/libcompat/4.1/cftime.3 index d346734d0d7b..5f7dd348507c 100644 --- a/lib/libcompat/4.1/cftime.3 +++ b/lib/libcompat/4.1/cftime.3 @@ -69,10 +69,11 @@ Use .Xr strftime 3 instead. .Pp -.Fn Ascftime -is almost identical with +The +.Fn ascftime +function is almost identical to .Xr strftime 3 , -with the only exception there's no parameter to tell about the +with the only exception that there's no parameter to tell about the maximal buffer length, and the .Fa format parameter defaults to @@ -81,8 +82,9 @@ if a .Em NULL pointer is given. .Pp -.Fn Cftime -does the same job, but it first invokes +The +.Fn cftime +function does the same job, but it first invokes .Xr localtime 3 in order to convert the given .Fa clock , diff --git a/lib/libcompat/4.4/cuserid.3 b/lib/libcompat/4.4/cuserid.3 index dc4bf536731c..168fcdaa3c75 100644 --- a/lib/libcompat/4.4/cuserid.3 +++ b/lib/libcompat/4.4/cuserid.3 @@ -68,8 +68,9 @@ If .Fa s is NULL, an internal array is used and its address will be returned. .Sh RETURN VALUES +The .Fn cuserid -returns the address of an array in which the name has been stored. +function returns the address of an array in which the name has been stored. .Pp If the name associated with the effective UID of the current process could not be found, either a null pointer will be returned, or diff --git a/lib/libipsec/ipsec_set_policy.3 b/lib/libipsec/ipsec_set_policy.3 index 00c3a6d0477f..5c63acffdda4 100644 --- a/lib/libipsec/ipsec_set_policy.3 +++ b/lib/libipsec/ipsec_set_policy.3 @@ -262,12 +262,14 @@ The .Fn ipsec_set_policy function returns a pointer to the allocated buffer of policy specification if successful; otherwise a NULL pointer is returned. +The .Fn ipsec_get_policylen -returns with positive value +function returns with positive value (meaning the buffer size) on success, and negative value on errors. +The .Fn ipsec_dump_policy -returns a pointer to dynamically allocated region on success, +function returns a pointer to dynamically allocated region on success, and .Dv NULL on errors. diff --git a/lib/libmd/mdX.3 b/lib/libmd/mdX.3 index 7c4b06ba136f..9e171ba1254b 100644 --- a/lib/libmd/mdX.3 +++ b/lib/libmd/mdX.3 @@ -72,27 +72,31 @@ run over the data with and finally extract the result using .Fn MDXFinal . .Pp +The .Fn MDXPad -can be used to pad message data in same way +function can be used to pad message data in same way as done by .Fn MDXFinal without terminating calculation. .Pp +The .Fn MDXEnd -is a wrapper for +function is a wrapper for .Fn MDXFinal which converts the return value to a 33-character (including the terminating '\e0') .Tn ASCII string which represents the 128 bits in hexadecimal. .Pp +The .Fn MDXFile -calculates the digest of a file, and uses +function calculates the digest of a file, and uses .Fn MDXEnd to return the result. If the file cannot be opened, a null pointer is returned. +The .Fn MDXFileChunk -is similar to +function is similar to .Fn MDXFile , but it only calculates the digest over a byte-range of the file specified, starting at @@ -108,8 +112,9 @@ of the file, calculates the digest from .Fa offset to the end of file. +The .Fn MDXData -calculates the digest of a chunk of data in memory, and uses +function calculates the digest of a chunk of data in memory, and uses .Fn MDXEnd to return the result. .Pp diff --git a/lib/libmd/ripemd.3 b/lib/libmd/ripemd.3 index 1f3aea1a123e..e86d6d1be6f4 100644 --- a/lib/libmd/ripemd.3 +++ b/lib/libmd/ripemd.3 @@ -62,21 +62,24 @@ run over the data with and finally extract the result using .Fn RIPEMD160_Final . .Pp +The .Fn RIPEMD160_End -is a wrapper for +function is a wrapper for .Fn RIPEMD160_Final which converts the return value to a 41-character (including the terminating '\e0') .Tn ASCII string which represents the 160 bits in hexadecimal. .Pp +The .Fn RIPEMD160_File -calculates the digest of a file, and uses +function calculates the digest of a file, and uses .Fn RIPEMD160_End to return the result. If the file cannot be opened, a null pointer is returned. +The .Fn RIPEMD160_FileChunk -is similar to +function is similar to .Fn RIPEMD160_File , but it only calculates the digest over a byte-range of the file specified, starting at @@ -92,8 +95,9 @@ of the file, calculates the digest from .Fa offset to the end of file. +The .Fn RIPEMD160_Data -calculates the digest of a chunk of data in memory, and uses +function calculates the digest of a chunk of data in memory, and uses .Fn RIPEMD160_End to return the result. .Pp diff --git a/lib/libutil/_secure_path.3 b/lib/libutil/_secure_path.3 index cd3cc259493d..0a19885a4d42 100644 --- a/lib/libutil/_secure_path.3 +++ b/lib/libutil/_secure_path.3 @@ -58,8 +58,9 @@ gid, if gid is not -1. This function returns zero if the file exists and may be considered secure, -2 if the file does not exist, and -1 otherwise to indicate a security failure. +The .Xr syslog 3 -is used to log any failure of this function, including the +function is used to log any failure of this function, including the reason, at LOG_ERR priority. .Sh BUGS The checks carried out are rudimentary and no attempt is made diff --git a/lib/libutil/login_cap.3 b/lib/libutil/login_cap.3 index f134d5546240..ccbb93f603ac 100644 --- a/lib/libutil/login_cap.3 +++ b/lib/libutil/login_cap.3 @@ -178,8 +178,9 @@ As noted above, the .Fn get*class functions return a login_cap_t object which is used to access the matching or default record in the capabilities database. +The .Fn getclassbyname -accepts two arguments: the first one is the record identifier of the +function accepts two arguments: the first one is the record identifier of the record to be retrieved, the second is an optional directory name. If the first .Ar name @@ -253,8 +254,9 @@ has no login class, then the system "default" entry is retrieved. Once a program no longer wishes to use a login_cap_t object, .Fn login_close may be called to free all resources used by the login class. +The .Fn login_close -may be passed a NULL pointer with no harmful side-effects. +function may be passed a NULL pointer with no harmful side-effects. .Pp The remaining functions may be used to retrieve individual capability records. diff --git a/lib/libutil/login_class.3 b/lib/libutil/login_class.3 index 4ad9dc75e47a..3f34fb0d08ab 100644 --- a/lib/libutil/login_class.3 +++ b/lib/libutil/login_class.3 @@ -57,13 +57,14 @@ and due care must be taken as detailed in the manpage for that function and this affects all processes running in the same session and not just the current process. .Pp +The .Fn setclasscontext -sets various class context values (resource limits, umask and +function sets various class context values (resource limits, umask and process priorities) based on values for a specific named class. .Pp -The function +The .Fn setusercontext -sets class context values based on a given login_cap_t +function sets class context values based on a given login_cap_t object, a specific passwd record (if login_cap_t is NULL), sets the current session's login and the current process user and group ownership. @@ -74,7 +75,7 @@ parameter, which is comprised of one or more of the following: .Bl -tag -width LOGIN_SETRESOURCES .It LOGIN_SETLOGIN Set the login associated with the current session to the user -specified in the passwd structure. +specified in the passwd structure using .Xr setlogin 2 . The .Ar pwd @@ -170,10 +171,11 @@ and functions are subsets of the setcontext functions above, but may be useful in isolation. .Sh RETURN VALUES +The .Fn setclasscontext and .Fn setusercontext -return -1 if an error occurred, or 0 on success. +functions return -1 if an error occurred, or 0 on success. If an error occurs when attempting to set the user, login, group or resources, a message is reported to .Xr syslog 3 , diff --git a/lib/libutil/login_ok.3 b/lib/libutil/login_ok.3 index c7fa84d6df08..c005e5d02e1f 100644 --- a/lib/libutil/login_ok.3 +++ b/lib/libutil/login_ok.3 @@ -44,8 +44,9 @@ This set of functions checks to see if login is allowed based on login class capability entries in the login database, .Xr login.conf 5 . .Pp +The .Fn auth_ttyok -checks to see if the named tty is available to users of a specific +function checks to see if the named tty is available to users of a specific class, and is either in the .Em ttys.allow access list, and not in @@ -73,8 +74,9 @@ or empty string as the .Ar tty parameter causes the function to return a non-zero value. .Pp +The .Fn auth_hostok -checks for any host restrictions for remote logins. +function checks for any host restrictions for remote logins. The function checks on both a host name and IP address (given in its text form, typically n.n.n.n) against the .Em host.allow diff --git a/lib/libutil/login_times.3 b/lib/libutil/login_times.3 index 10824049a17d..9419c7f60a09 100644 --- a/lib/libutil/login_times.3 +++ b/lib/libutil/login_times.3 @@ -114,8 +114,9 @@ then a parsing error was encountered. The remaining functions provide the ability to test a given time_t or struct tm value against a specific time period or array of time periods. +The .Fn in_ltm -determines whether the given time described by the struct tm +function determines whether the given time described by the struct tm passed as the second parameter falls within the period described by the first parameter. A boolean value is returned, indicating whether or not the time @@ -135,19 +136,22 @@ elements in length, and terminated by an element with its field set to .Em LTM_NONE . .Sh RETURN VALUES +The .Fn parse_lt -returns a filled in structure of type login_time_t containing the +function returns a filled in structure of type login_time_t containing the parsed time period. If a parsing error occurs, the lt_dow field is set to .Em LTM_NONE (i.e. 0). .Pp +The .Fn in_ltm -returns non-zero if the given time falls within the period described +function returns non-zero if the given time falls within the period described by the login_time_t passed as the first parameter. .Pp +The .Fn in_ltms -returns the index of the first time period found in which the given +function returns the index of the first time period found in which the given time falls, or -1 if none of them apply. .Sh SEE ALSO .Xr getcap 3 , diff --git a/lib/libutil/login_tty.3 b/lib/libutil/login_tty.3 index af3eaaf3d728..b7111e75af61 100644 --- a/lib/libutil/login_tty.3 +++ b/lib/libutil/login_tty.3 @@ -51,8 +51,9 @@ a new session with This terminal device will also be made the standard input, standard output, and standard error output of the calling process. .Sh RETURN VALUES -.Fn Login_tty -returns -1 if it could not make the device referenced by +The +.Fn login_tty +function returns -1 if it could not make the device referenced by .Ar fd the controlling terminal of the calling process, and 0 otherwise. .Sh SEE ALSO diff --git a/lib/libutil/logout.3 b/lib/libutil/logout.3 index d5beb7fc7202..2fe2d4f4a54e 100644 --- a/lib/libutil/logout.3 +++ b/lib/libutil/logout.3 @@ -52,8 +52,9 @@ and .Em host fields are empty, and the time stamp field is updated to the current time. .Sh RETURN VALUES -.Fn Logout -returns 1 if the slot described by +The +.Fn logout +function returns 1 if the slot described by .Ar line has been found and updated, 0 otherwise. .Sh SEE ALSO diff --git a/lib/libutil/property.3 b/lib/libutil/property.3 index 219c0e7c9782..d9b5d1279d03 100644 --- a/lib/libutil/property.3 +++ b/lib/libutil/property.3 @@ -63,15 +63,17 @@ and returns the head of a new property list, assuming that the file's contents have been parsed properly, or NULL in case of error. .Pp +The .Fn property_find -Returns the associated value string for the property named +function returns the associated value string for the property named .Fa name if found, otherwise NULL. The value returned may be up to .Dv PROPERTY_MAX_VALUE bytes in length. .Pp +The .Fn properties_free -is used to free the structure returned by +function is used to free the structure returned by .Fn properties_read when it is no longer needed. .Sh FILE FORMAT diff --git a/lib/libutil/pty.3 b/lib/libutil/pty.3 index 30c9f96f6915..19cf9f7d3564 100644 --- a/lib/libutil/pty.3 +++ b/lib/libutil/pty.3 @@ -82,8 +82,9 @@ and .Fa aslave , respectively. .Pp -.Fn Forkpty -first calls +The +.Fn forkpty +function first calls .Fn openpty to obtain the next available pseudo-terminal from the system. Upon success, it forks off a new process. In the child process, it closes the descriptor @@ -99,12 +100,14 @@ and have the same meaning as described for .Fn openpty . .Sh RETURN VALUES -.Fn Openpty -returns 0 on success, or -1 on failure. +The +.Fn openpty +function returns 0 on success, or -1 on failure. .Pp -.Fn Forkpty -returns -1 on failure, 0 in the slave process, and the process ID of the -slave process in the parent process. +The +.Fn forkpty +function returns -1 on failure, 0 in the slave process, and the process ID of +the slave process in the parent process. .Sh ERRORS On failure, .Fn openpty diff --git a/lib/libutil/realhostname.3 b/lib/libutil/realhostname.3 index 1b4ae3d8c31c..a77c44cf1d3d 100644 --- a/lib/libutil/realhostname.3 +++ b/lib/libutil/realhostname.3 @@ -71,8 +71,9 @@ bytes long, .Ar host will not be NUL terminated. .Sh RETURN VALUES +The .Fn realhostname -will return one of the following constants which are defined in +function will return one of the following constants which are defined in .Pa libutil.h : .Pp .Bl -tag -width XXX -offset XXX diff --git a/lib/libutil/realhostname_sa.3 b/lib/libutil/realhostname_sa.3 index fdeb099bea31..73d89f7ad3d7 100644 --- a/lib/libutil/realhostname_sa.3 +++ b/lib/libutil/realhostname_sa.3 @@ -100,8 +100,9 @@ bytes long, .Ar host will not be NUL terminated. .Sh RETURN VALUES +The .Fn realhostname_sa -will return one of the following constants which are defined in +function will return one of the following constants which are defined in .Pa libutil.h : .Pp .Bl -tag -width XXX -offset XXX diff --git a/lib/libutil/trimdomain.3 b/lib/libutil/trimdomain.3 index 2b6dd75c19b3..66b8369ae1fb 100644 --- a/lib/libutil/trimdomain.3 +++ b/lib/libutil/trimdomain.3 @@ -50,8 +50,9 @@ name is determined by calling and removing everything up to the first period. The name is determined the first time this function is called and is cached for future use. .Pp +The .Fn trimdomain -will only trim the domain name if the passed +function will only trim the domain name if the passed .Ar fullname ends with the current domain name and if the length of the resulting host name does not exceed @@ -75,7 +76,8 @@ numbers to the end of the base host name and resulting in .Ar host : nn Op . Ar nn . .Sm on .Sh RETURN VALUES +The .Fn trimdomain -does not return a value. +function does not return a value. .Sh SEE ALSO .Xr gethostname 3