Index: head/contrib/bsnmp/snmpd/snmpmod.3 =================================================================== --- head/contrib/bsnmp/snmpd/snmpmod.3 (revision 332641) +++ head/contrib/bsnmp/snmpd/snmpmod.3 (revision 332642) @@ -1,1184 +1,1184 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" .\" Author: Harti Brandt .\" .\" 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 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 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. .\" .\" $Begemot: bsnmp/snmpd/snmpmod.3,v 1.14 2005/10/04 13:30:35 brandt_h Exp $ .\" .Dd December 19, 2010 .Dt SNMPMOD 3 .Os .Sh NAME .Nm INSERT_OBJECT_OID_LINK_INDEX , .Nm INSERT_OBJECT_INT_LINK_INDEX , .Nm FIND_OBJECT_OID_LINK_INDEX , .Nm NEXT_OBJECT_OID_LINK_INDEX , .Nm FIND_OBJECT_INT_LINK_INDEX , .Nm NEXT_OBJECT_INT_LINK_INDEX , .Nm INSERT_OBJECT_OID_LINK , .Nm INSERT_OBJECT_INT_LINK , .Nm FIND_OBJECT_OID_LINK , .Nm NEXT_OBJECT_OID_LINK , .Nm FIND_OBJECT_INT_LINK , .Nm NEXT_OBJECT_INT_LINK , .Nm INSERT_OBJECT_OID , .Nm INSERT_OBJECT_INT , .Nm FIND_OBJECT_OID , .Nm FIND_OBJECT_INT , .Nm NEXT_OBJECT_OID , .Nm NEXT_OBJECT_INT , .Nm this_tick , .Nm start_tick , .Nm get_ticks , .Nm systemg , .Nm comm_define , .Nm community , .Nm oid_zeroDotZero , .Nm oid_usmUnknownEngineIDs , .Nm oid_usmNotInTimeWindows , .Nm reqid_allocate , .Nm reqid_next , .Nm reqid_base , .Nm reqid_istype , .Nm reqid_type , .Nm timer_start , .Nm timer_start_repeat , .Nm timer_stop , .Nm fd_select , .Nm fd_deselect , .Nm fd_suspend , .Nm fd_resume , .Nm or_register , .Nm or_unregister , .Nm buf_alloc , .Nm buf_size , .Nm snmp_input_start , .Nm snmp_input_finish , .Nm snmp_output , .Nm snmp_send_port , .Nm snmp_send_trap , .Nm snmp_pdu_auth_access .Nm string_save , .Nm string_commit , .Nm string_rollback , .Nm string_get , .Nm string_get_max , .Nm string_free , .Nm ip_save , .Nm ip_rollback , .Nm ip_commit , .Nm ip_get , .Nm oid_save , .Nm oid_rollback , .Nm oid_commit , .Nm oid_get , .Nm index_decode , .Nm index_compare , .Nm index_compare_off , .Nm index_append , -.Nm index_append_off, -.Nm snmpd_usmstats, -.Nm bsnmpd_get_usm_stats, -.Nm bsnmpd_reset_usm_stats, -.Nm usm_first_user, -.Nm usm_next_user, -.Nm usm_find_user, -.Nm usm_new_user, -.Nm usm_delete_user, -.Nm usm_flush_users, -.Nm usm_user -.Nm snmpd_target_stat -.Nm bsnmpd_get_target_stats -.Nm target_first_address -.Nm target_next_address -.Nm target_new_address -.Nm target_activate_address -.Nm target_delete_address -.Nm target_first_param -.Nm target_next_param -.Nm target_new_param -.Nm target_delete_param -.Nm target_first_notify -.Nm target_next_notify -.Nm target_new_notify -.Nm target_delete_notify -.Nm target_flush_all -.Nm target_address -.Nm target_param +.Nm index_append_off , +.Nm snmpd_usmstats , +.Nm bsnmpd_get_usm_stats , +.Nm bsnmpd_reset_usm_stats , +.Nm usm_first_user , +.Nm usm_next_user , +.Nm usm_find_user , +.Nm usm_new_user , +.Nm usm_delete_user , +.Nm usm_flush_users , +.Nm usm_user , +.Nm snmpd_target_stat , +.Nm bsnmpd_get_target_stats , +.Nm target_first_address , +.Nm target_next_address , +.Nm target_new_address , +.Nm target_activate_address , +.Nm target_delete_address , +.Nm target_first_param , +.Nm target_next_param , +.Nm target_new_param , +.Nm target_delete_param , +.Nm target_first_notify , +.Nm target_next_notify , +.Nm target_new_notify , +.Nm target_delete_notify , +.Nm target_flush_all , +.Nm target_address , +.Nm target_param , .Nm target_notify .Nd "SNMP daemon loadable module interface" .Sh LIBRARY Begemot SNMP library .Pq libbsnmp, -lbsnmp .Sh SYNOPSIS .In bsnmp/snmpmod.h .Fn INSERT_OBJECT_OID_LINK_INDEX "PTR" "LIST" "LINK" "INDEX" .Fn INSERT_OBJECT_INT_LINK_INDEX "PTR" "LIST" "LINK" "INDEX" .Fn FIND_OBJECT_OID_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX" .Fn FIND_OBJECT_INT_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX" .Fn NEXT_OBJECT_OID_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX" .Fn NEXT_OBJECT_INT_LINK_INDEX "LIST" "OID" "SUB" "LINK" "INDEX" .Fn INSERT_OBJECT_OID_LINK "PTR" "LIST" "LINK" .Fn INSERT_OBJECT_INT_LINK "PTR" "LIST" "LINK" .Fn FIND_OBJECT_OID_LINK "LIST" "OID" "SUB" "LINK" .Fn FIND_OBJECT_INT_LINK "LIST" "OID" "SUB" "LINK" .Fn NEXT_OBJECT_OID_LINK "LIST" "OID" "SUB" "LINK" .Fn NEXT_OBJECT_INT_LINK "LIST" "OID" "SUB" "LINK" .Fn INSERT_OBJECT_OID "PTR" "LIST" .Fn INSERT_OBJECT_INT "PTR" "LIST" .Fn FIND_OBJECT_OID "LIST" "OID" "SUB" .Fn FIND_OBJECT_INT "LIST" "OID" "SUB" .Fn NEXT_OBJECT_OID "LIST" "OID" "SUB" .Fn NEXT_OBJECT_INT "LIST" "OID" "SUB" .Vt extern uint64_t this_tick ; .Vt extern uint64_t start_tick ; .Ft uint64_t .Fn get_ticks "void" .Vt extern struct systemg systemg ; .Ft u_int .Fn comm_define "u_int priv" "const char *descr" "struct lmodule *mod" "const char *str" .Ft const char * .Fn comm_string "u_int comm" .Vt extern u_int community ; .Vt extern const struct asn_oid oid_zeroDotZero ; .Ft u_int .Fn reqid_allocate "int size" "struct lmodule *mod" .Ft int32_t .Fn reqid_next "u_int type" .Ft int32_t .Fn reqid_base "u_int type" .Ft int .Fn reqid_istype "int32_t reqid" "u_int type" .Ft u_int .Fn reqid_type "int32_t reqid" .Ft void * .Fn timer_start "u_int ticks" "void (*func)(void *)" "void *uarg" "struct lmodule *mod" .Ft void * .Fn timer_start_repeat "u_int ticks" "u_int repeat_ticks" "void (*func)(void *)" "void *uarg" "struct lmodule *mod" .Ft void .Fn timer_stop "void *timer_id" .Ft void * .Fn fd_select "int fd" "void (*func)(int, void *)" "void *uarg" "struct lmodule *mod" .Ft void .Fn fd_deselect "void *fd_id" .Ft void .Fn fd_suspend "void *fd_id" .Ft int .Fn fd_resume "void *fd_id" .Ft u_int .Fn or_register "const struct asn_oid *oid" "const char *descr" "struct lmodule *mod" .Ft void .Fn or_unregister "u_int or_id" .Ft void * .Fn buf_alloc "int tx" .Ft size_t .Fn buf_size "int tx" .Ft enum snmpd_input_err .Fo snmp_input_start .Fa "const u_char *buf" "size_t len" "const char *source" .Fa "struct snmp_pdu *pdu" "int32_t *ip" "size_t *pdulen" .Fc .Ft enum snmpd_input_err .Fo snmp_input_finish .Fa "struct snmp_pdu *pdu" "const u_char *rcvbuf" .Fa "size_t rcvlen" "u_char *sndbuf" "size_t *sndlen" "const char *source" .Fa "enum snmpd_input_err ierr" "int32_t ip" "void *data" .Fc .Ft void .Fo snmp_output .Fa "struct snmp_pdu *pdu" "u_char *sndbuf" "size_t *sndlen" .Fa "const char *dest" .Fc .Ft void .Fo snmp_send_port .Fa "void *trans" "const struct asn_oid *port" .Fa "struct snmp_pdu *pdu" "const struct sockaddr *addr" "socklen_t addrlen" .Fc .Ft void .Fn snmp_send_trap "const struct asn_oid *oid" "..." .Ft enum snmp_code .Fn snmp_pdu_auth_access "struct snmp_pdu *pdu" "int32_t *ip" .Ft int .Fn string_save "struct snmp_value *val" "struct snmp_context *ctx" "ssize_t req_size" "u_char **strp" .Ft void .Fn string_commit "struct snmp_context *ctx" .Ft void .Fn string_rollback "struct snmp_context *ctx" "u_char **strp" .Ft int .Fn string_get "struct snmp_value *val" "const u_char *str" "ssize_t len" .Ft int .Fn string_get_max "struct snmp_value *val" "const u_char *str" "ssize_t len" "size_t maxlen" .Ft void .Fn string_free "struct snmp_context *ctx" .Ft int .Fn ip_save "struct snmp_value *val" "struct snmp_context *ctx" "u_char *ipa" .Ft void .Fn ip_rollback "struct snmp_context *ctx" "u_char *ipa" .Ft void .Fn ip_commit "struct snmp_context *ctx" .Ft int .Fn ip_get "struct snmp_value *val" "u_char *ipa" .Ft int .Fn oid_save "struct snmp_value *val" "struct snmp_context *ctx" "struct asn_oid *oid" .Ft void .Fn oid_rollback "struct snmp_context *ctx" "struct asn_oid *oid" .Ft void .Fn oid_commit "struct snmp_context *ctx" .Ft int .Fn oid_get "struct snmp_value *val" "const struct asn_oid *oid" .Ft int .Fn index_decode "const struct asn_oid *oid" "u_int sub" "u_int code" "..." .Ft int .Fn index_compare "const struct asn_oid *oid1" "u_int sub" "const struct asn_oid *oid2" .Ft int .Fn index_compare_off "const struct asn_oid *oid1" "u_int sub" "const struct asn_oid *oid2" "u_int off" .Ft void .Fn index_append "struct asn_oid *dst" "u_int sub" "const struct asn_oid *src" .Ft void .Fn index_append_off "struct asn_oid *dst" "u_int sub" "const struct asn_oid *src" "u_int off" .Vt extern struct snmpd_usmstat snmpd_usmstats ; .Ft struct snmpd_usmstat * .Fn bsnmpd_get_usm_stats "void" .Ft void .Fn bsnmpd_reset_usm_stats "void" .Ft struct usm_user * .Fn usm_first_user "void" .Ft struct usm_user * .Fn usm_next_user "struct usm_user *uuser" .Ft struct usm_user * .Fn usm_find_user "uint8_t *engine" "uint32_t elen" "char *uname" .Ft struct usm_user * .Fn usm_new_user "uint8_t *engine" "uint32_t elen" "char *uname" .Ft void .Fn usm_delete_user "struct usm_user *" .Ft void .Fn usm_flush_users "void" .Vt extern struct usm_user *usm_user; .Ft struct snmpd_target_stats * .Fn bsnmpd_get_target_stats "void" .Ft struct target_address * .Fn target_first_address "void" .Ft struct target_address * .Fn target_next_address "struct target_address *" .Ft struct target_address * .Fn target_new_address "char *" .Ft int .Fn target_activate_address "struct target_address *" .Ft int .Fn target_delete_address "struct target_address *" .Ft struct target_param * .Fn target_first_param "void" .Ft struct target_param * .Fn target_next_param "struct target_param *" .Ft struct target_param * .Fn target_new_param "char *" .Ft int .Fn target_delete_param "struct target_param *" .Ft struct target_notify * .Fn target_first_notify "void" .Ft struct target_notify * .Fn target_next_notify "struct target_notify *" .Ft struct target_notify * .Fn target_new_notify "char *" .Ft int .Fn target_delete_notify "struct target_notify *" .Ft void .Fn target_flush_all "void" .Vt extern const struct asn_oid oid_usmUnknownEngineIDs; .Vt extern const struct asn_oid oid_usmNotInTimeWindows; .Sh DESCRIPTION The .Xr bsnmpd 1 SNMP daemon implements a minimal MIB which consists of the system group, part of the SNMP MIB, a private configuration MIB, a trap destination table, a UDP port table, a community table, a module table, a statistics group and a debugging group. All other MIBs are support through loadable modules. This allows .Xr bsnmpd 1 to use for task, that are not the classical SNMP task. .Ss MODULE LOADING AND UNLOADING Modules are loaded by writing to the module table. This table is indexed by a string, that identifies the module to the daemon. This identifier is used to select the correct configuration section from the configuration files and to identify resources allocated to this module. A row in the module table is created by writing a string of non-zero length to the .Va begemotSnmpdModulePath column. This string must be the complete path to the file containing the module. A module can be unloaded by writing a zero length string to the path column of an existing row. .Pp Modules may depend on each other an hence must be loaded in the correct order. The dependencies are listed in the corresponding manual pages. .Pp Upon loading a module the SNMP daemon expects the module file to a export a global symbol .Va config . This symbol should be a variable of type .Vt struct snmp_module : .Bd -literal -offset indent typedef enum snmpd_proxy_err (*proxy_err_f)(struct snmp_pdu *, void *, const struct asn_oid *, const struct sockaddr *, socklen_t, enum snmpd_input_err, int32_t); struct snmp_module { const char *comment; int (*init)(struct lmodule *, int argc, char *argv[]); int (*fini)(void); void (*idle)(void); void (*dump)(void); void (*config)(void); void (*start)(void); proxy_err_f proxy; const struct snmp_node *tree; u_int tree_size; void (*loading)(const struct lmodule *, int); }; .Ed .Pp This structure must be statically initialized and its fields have the following functions: .Bl -tag -width ".It Va tree_size" .It Va comment This is a string that will be visible in the module table. It should give some hint about the function of this module. .It Va init This function is called upon loading the module. The module pointer should be stored by the module because it is needed in other calls and the argument vector will contain the arguments to this module from the daemons command line. This function should return 0 if everything is ok or an UNIX error code (see .Xr errno 3 ) . Once the function returns 0, the .Va fini function is called when the module is unloaded. .It Va fini The module is unloaded. This gives the module a chance to free resources that are not automatically freed. Be sure to free all memory, because daemons tend to run very long. This function pointer may be .Li NULL if it is not needed. .It Va idle If this function pointer is not .Li NULL , the function pointed to by it is called whenever the daemon is going to wait for an event. Try to avoid using this feature. .It Va dump Whenever the daemon receives a .Li SIGUSR1 it dumps it internal state via .Xr syslog 3 . If the .Va dump field is not .Li NULL it is called by the daemon to dump the state of the module. .It Va config Whenever the daemon receives a .Li SIGHUP signal it re-reads its configuration file. If the .Va config field is not .Li NULL it is called after reading the configuration file to give the module a chance to adapt to the new configuration. .It Va start If not .Li NULL this function is called after successful loading and initializing the module to start its actual operation. .It Va proxy If the daemon receives a PDU and that PDU has a community string whose community was registered by this module and .Va proxy is not .Li NULL than this function is called to handle the PDU. .It Va tree This is a pointer to the node array for the MIB tree implemented by this module. .It Va tree_size This is the number of nodes in .Va tree . .It Va loading If this pointer is not .Li NULL it is called whenever another module was loaded or unloaded. It gets a pointer to that module and a flag that is 0 for unloading and 1 for loading. .El .Pp When everything is ok, the daemon merges the module's MIB tree into its current global tree, calls the modules .Fn init function. If this function returns an error, the modules MIB tree is removed from the global one and the module is unloaded. If initialization is successful, the modules .Fn start function is called. After it returns the .Fn loaded functions of all modules (including the loaded one) are called. .Pp When the module is unloaded, its MIB tree is removed from the global one, the communities, request id ranges, running timers and selected file descriptors are released, the .Fn fini function is called, the module file is unloaded and the .Fn loaded functions of all other modules are called. .Ss IMPLEMENTING TABLES There are a number of macros designed to help implementing SNMP tables. A problem while implementing a table is the support for the GETNEXT operator. The GETNEXT operation has to find out whether, given an arbitrary OID, the lessest table row, that has an OID higher than the given OID. The easiest way to do this is to keep the table as an ordered list of structures each one of which contains an OID that is the index of the table row. This allows easy removal, insertion and search. .Pp The helper macros assume, that the table is organized as a TAILQ (see .Xr queue 3 and each structure contains a .Vt struct asn_oid that is used as index. For simple tables with only a integer or unsigned index, an alternate form of the macros is available, that presume the existence of an integer or unsigned field as index field. .Pp The macros have name of the form .Bd -literal -offset indent {INSERT,FIND,NEXT}_OBJECT_{OID,INT}[_LINK[_INDEX]] .Ed .Pp The .Fn INSERT_* macros are used in the SET operation to insert a new table row into the table. The .Fn FIND_* macros are used in the GET operation to find a specific row in the table. The .Fn NEXT_* macros are used in the GETNEXT operation to find the next row in the table. The last two macros return a pointer to the row structure if a row is found, .Li NULL otherwise. The macros .Fn *_OBJECT_OID_* assume the existence of a .Vt struct asn_oid that is used as index, the macros .Fn *_OBJECT_INT_* assume the existence of an unsigned integer field that is used as index. .Pp The macros .Fn *_INDEX allow the explicit naming of the index field in the parameter .Fa INDEX , whereas the other macros assume that this field is named .Va index . The macros .Fn *_LINK_* allow the explicit naming of the link field of the tail queues, the others assume that the link field is named .Va link . Explicitly naming the link field may be necessary if the same structures are held in two or more different tables. .Pp The arguments to the macros are as follows: .Bl -tag -width "INDEX" .It Fa PTR A pointer to the new structure to be inserted into the table. .It Fa LIST A pointer to the tail queue head. .It Fa LINK The name of the link field in the row structure. .It Fa INDEX The name of the index field in the row structure. .It Fa OID Must point to the .Va var field of the .Fa value argument to the node operation callback. This is the OID to search for. .It Fa SUB This is the index of the start of the table index in the OID pointed to by .Fa OID . This is usually the same as the .Fa sub argument to the node operation callback. .El .Ss DAEMON TIMESTAMPS The variable .Va this_tick contains the tick (there are 100 SNMP ticks in a second) when the current PDU processing was started. The variable .Va start_tick contains the tick when the daemon was started. The function .Fn get_ticks returns the current tick. The number of ticks since the daemon was started is .Bd -literal -offset indent get_ticks() - start_tick .Ed .Ss THE SYSTEM GROUP The scalar fields of the system group are held in the global variable .Va systemg : .Bd -literal -offset indent struct systemg { u_char *descr; struct asn_oid object_id; u_char *contact; u_char *name; u_char *location; uint32_t services; uint32_t or_last_change; }; .Ed .Ss COMMUNITIES The SNMP daemon implements a community table. On recipte of a request message the community string in that message is compared to each of the community strings in that table, if a match is found, the global variable .Va community is set to the community identifier for that community. Community identifiers are unsigned integers. For the three standard communities there are three constants defined: .Bd -literal -offset indent #define COMM_INITIALIZE 0 #define COMM_READ 1 #define COMM_WRITE 2 .Ed .Pp .Va community is set to .Li COMM_INITIALIZE while the assignments in the configuration file are processed. To .Li COMM_READ or .Li COMM_WRITE when the community strings for the read-write or read-only community are found in the incoming PDU. .Pp Modules can define additional communities. This may be necessary to provide transport proxying (a PDU received on one communication link is proxied to another link) or to implement non-UDP access points to SNMP. A new community is defined with the function .Fn comm_define . It takes the following parameters: .Bl -tag -width ".It Fa descr" .It Fa priv This is an integer identifying the community to the module. Each module has its own namespace with regard to this parameter. The community table is indexed with the module name and this identifier. .It Fa descr This is a string providing a human readable description of the community. It is visible in the community table. .It Fa mod This is the module defining the community. .It Fa str This is the initial community string. .El .Pp The function returns a globally unique community identifier. If a SNMPv1 or SNMPv2 PDU is received who's community string matches, this identifier is set into the global .Va community . .Pp The function .Fn comm_string returns the current community string for the given community. .Pp All communities defined by a module are automatically released when the module is unloaded. .Ss THE USER-BASED SECURITY GROUP The scalar statistics of the USM group are held in the global variable .Va snmpd_usmstats : .Bd -literal -offset indent struct snmpd_usmstat { uint32_t unsupported_seclevels; uint32_t not_in_time_windows; uint32_t unknown_users; uint32_t unknown_engine_ids; uint32_t wrong_digests; uint32_t decrypt_errors; }; .Ed .Fn bsnmpd_get_usm_stats returns a pointer to the global structure containing the statistics. .Fn bsnmpd_reset_usm_stats clears the statistics of the USM group. .Pp A global list of configured USM users is maintained by the daemon. .Bd -literal -offset indent struct usm_user { struct snmp_user suser; uint8_t user_engine_id[SNMP_ENGINE_ID_SIZ]; uint32_t user_engine_len; char user_public[SNMP_ADM_STR32_SIZ]; uint32_t user_public_len; int32_t status; int32_t type; SLIST_ENTRY(usm_user) up; }; .Ed This structure represents an USM user. The daemon only responds to SNMPv3 PDUs with user credentials matching an USM user entry in its global list. If a SNMPv3 PDU is received, whose security model is USM, the global .Va usm_user is set to point at the user entry that matches the credentials contained in the PDU. However, the daemon does not create or remove USM users, it gives an interface to external loadable module(s) to manage the list. .Fn usm_new_user adds an user entry in the list, and .Fn usm_delete_user deletes an existing entry from the list. .Fn usm_flush_users is used to remove all configured USM users. .Fn usm_first_user will return the first user in the list, or .Li NULL if the list is empty. .Fn usm_next_user will return the next user of a given entry if one exists, or .Li NULL . The list is sorted according to the USM user name and Engine ID. .Fn usm_find_user returns the USM user entry matching the given .Fa engine and .Fa uname or .Li NULL if an user with the specified name and engine id is not present in the list. .Ss THE MANAGEMENT TARGET GROUP The Management Target group holds target address information used when sending SNMPv3 notifications. .Pp The scalar statistics of the Management Target group are held in the global variable .Va snmpd_target_stats : .Bd -literal -offset indent struct snmpd_target_stats { uint32_t unavail_contexts; uint32_t unknown_contexts; }; .Ed .Fn bsnmpd_get_target_stats returns a pointer to the global structure containing the statistics. .Pp Three global lists of configured management target addresses, parameters and notifications respectively are maintained by the daemon. .Bd -literal -offset indent struct target_address { char name[SNMP_ADM_STR32_SIZ]; uint8_t address[SNMP_UDP_ADDR_SIZ]; int32_t timeout; int32_t retry; char taglist[SNMP_TAG_SIZ]; char paramname[SNMP_ADM_STR32_SIZ]; int32_t type; int32_t socket; int32_t status; SLIST_ENTRY(target_address) ta; }; .Ed This structure represents a SNMPv3 Management Target address. Each time a SNMP TRAP is send the daemon will send the Trap to all active Management Target addresses in its global list. .Bd -literal -offset indent struct target_param { char name[SNMP_ADM_STR32_SIZ]; int32_t mpmodel; int32_t sec_model; char secname[SNMP_ADM_STR32_SIZ]; enum snmp_usm_level sec_level; int32_t type; int32_t status; SLIST_ENTRY(target_param) tp; }; .Ed This structure represents the information used to generate SNMP messages to the associated SNMPv3 Management Target addresses. .Bd -literal -offset indent struct target_notify { char name[SNMP_ADM_STR32_SIZ]; char taglist[SNMP_TAG_SIZ]; int32_t notify_type; int32_t type; int32_t status; SLIST_ENTRY(target_notify) tn; }; .Ed This structure represents Notification Tag entries - SNMP notifications are sent to the Target address for each entry in the Management Target Address list that has a tag matching the specified tag in this structure. .Pp The daemon does not create or remove entries in the Management Target group lists, it gives an interface to external loadable module(s) to manage the lists. .Fn target_new_address adds a target address entry, and .Fn target_delete_address deletes an existing entry from the target address list. .Fn target_activate_address creates a socket associated with the target address entry so that SNMP notifications may actually be send to that target address. .Fn target_first_address will return a pointer to the first target address entry in the list, while .Fn target_next_address will return a pointer to the next target address of a given entry if one exists. .Fn target_new_param adds a target parameters' entry, and .Fn target_delete_param deletes an existing entry from the target parameters list. .Fn target_first_param will return a pointer to the first target parameters' entry in the list, while .Fn target_next_param will return a pointer to the next target parameters of a given entry if one exists. .Fn target_new_notify adds a notification target entry, and .Fn target_delete_notify deletes an existing entry from the notification target list. .Fn target_first_notify will return a pointer to the first notification target entry in the list, while .Fn target_next_notify will return a pointer to the next notification target of a given entry if one exists. .Fn target_flush_all is used to remove all configured data from the three global Management Target Group lists. .Ss WELL KNOWN OIDS The global variable .Va oid_zeroDotZero contains the OID 0.0. The global variables .Va oid_usmUnknownEngineIDs .Va oid_usmNotInTimeWindows contains the OIDs 1.3.6.1.6.3.15.1.1.4.0 and 1.3.6.1.6.3.15.1.1.2.0 used in the SNMPv3 USM Engine Discovery. .Ss REQUEST ID RANGES For modules that implement SNMP client functions besides SNMP agent functions it may be necessary to identify SNMP requests by their identifier to allow easier routing of responses to the correct sub-system. Request id ranges provide a way to acquire globally non-overlapping sub-ranges of the entire 31-bit id range. .Pp A request id range is allocated with .Fn reqid_allocate . The arguments are: the size of the range and the module allocating the range. For example, the call .Bd -literal -offset indent id = reqid_allocate(1000, module); .Ed .Pp allocates a range of 1000 request ids. The function returns the request id range identifier or 0 if there is not enough identifier space. The function .Fn reqid_base returns the lowest request id in the given range. .Pp Request id are allocated starting at the lowest one linear throughout the range. If the client application may have a lot of outstanding request the range must be large enough so that an id is not reused until it is really expired. .Fn reqid_next returns the sequentially next id in the range. .Pp The function .Fn reqid_istype checks whether the request id .Fa reqid is within the range identified by .Fa type . The function .Fn reqid_type returns the range identifier for the given .Fa reqid or 0 if the request id is in none of the ranges. .Ss TIMERS The SNMP daemon supports an arbitrary number of timers with SNMP tick granularity. The function .Fn timer_start arranges for the callback .Fa func to be called with the argument .Fa uarg after .Fa ticks SNMP ticks have expired. .Fa mod is the module that starts the timer. These timers are one-shot, they are not restarted. Repeatable timers are started with .Fn timer_start_repeat which takes an additional argument .Fa repeat_ticks . The argument .Fa ticks gives the number of ticks until the first execution of the callback, while .Fa repeat_ticks is the number of ticks between invocations of the callback. Note, that currently the number of initial ticks silently may be set identical to the number of ticks between callback invocations. The function returns a timer identifier that can be used to stop the timer via .Fn timer_stop . If a module is unloaded all timers started by the module that have not expired yet are stopped. .Ss FILE DESCRIPTOR SUPPORT A module may need to get input from socket file descriptors without blocking the daemon (for example to implement alternative SNMP transports). .Pp The function .Fn fd_select causes the callback function .Fa func to be called with the file descriptor .Fa fd and the user argument .Fa uarg whenever the file descriptor .Fa fd can be read or has a close condition. If the file descriptor is not in non-blocking mode, it is set to non-blocking mode. If the callback is not needed anymore, .Fn fd_deselect may be called with the value returned from .Fn fd_select . All file descriptors selected by a module are automatically deselected when the module is unloaded. .Pp To temporarily suspend the file descriptor registration .Fn fd_suspend can be called. This also causes the file descriptor to be switched back to blocking mode if it was blocking prior the call to .Fn fd_select . This is necessary to do synchronous input on a selected socket. The effect of .Fn fd_suspend can be undone with .Fn fd_resume . .Ss OBJECT RESOURCES The system group contains an object resource table. A module may create an entry in this table by calling .Fn or_register with the .Fa oid to be registered, a textual description in .Fa str and a pointer to the module .Fa mod . The registration can be removed with .Fn or_unregister . All registrations of a module are automatically removed if the module is unloaded. .Ss TRANSMIT AND RECEIVE BUFFERS A buffer is allocated via .Fn buf_alloc . The argument must be 1 for transmit and 0 for receive buffers. The function may return .Li NULL if there is no memory available. The current buffersize can be obtained with .Fn buf_size . .Sh PROCESSING PDUS For modules that need to do their own PDU processing (for example for proxying) the following functions are available: .Pp Function .Fn snmp_input_start decodes the PDU, searches the community, and sets the global .Va this_tick . It returns one of the following error codes: .Bl -tag -width ".It Er SNMPD_INPUT_VALBADLEN" .It Er SNMPD_INPUT_OK Everything ok, continue with processing. .It Er SNMPD_INPUT_FAILED The PDU could not be decoded, has a wrong version or an unknown community string. .It Er SNMPD_INPUT_VALBADLEN A SET PDU had a value field in a binding with a wrong length field in an ASN.1 header. .It Er SNMPD_INPUT_VALRANGE A SET PDU had a value field in a binding with a value that is out of range for the given ASN.1 type. .It Er SNMPD_INPUT_VALBADENC A SET PDU had a value field in a binding with wrong ASN.1 encoding. .It Er SNMPD_INPUT_TRUNC The buffer appears to contain a valid begin of a PDU, but is too short. For streaming transports this means that the caller must save what he already has and trying to obtain more input and reissue this input to the function. For datagram transports this means that part of the datagram was lost and the input should be ignored. .El .Pp The function .Fn snmp_input_finish does the other half of processing: if .Fn snmp_input_start did not return OK, tries to construct an error response. If the start was OK, it calls the correct function from .Xr bsnmpagent 3 to execute the request and depending on the outcome constructs a response or error response PDU or ignores the request PDU. It returns either .Er SNMPD_INPUT_OK or .Er SNMPD_INPUT_FAILED . In the first case a response PDU was constructed and should be sent. .Pp The function .Fn snmp_output takes a PDU and encodes it. .Pp The function .Fn snmp_send_port takes a PDU, encodes it and sends it through the given port (identified by the transport and the index in the port table) to the given address. .Pp The function .Fn snmp_send_trap sends a trap to all trap destinations. The arguments are the .Fa oid identifying the trap and a NULL-terminated list of .Vt struct snmp_value pointers that are to be inserted into the trap binding list. .Fn snmp_pdu_auth_access verifies whether access to the object IDs contained in the .Fa pdu should be granted or denied, according to the configured View-Based Access rules. .Fa ip contains the index of the first varbinding to which access was denied, or 0 if access to all varbindings in the PDU is granted. .Ss SIMPLE ACTION SUPPORT For simple scalar variables that need no dependencies a number of support functions is available to handle the set, commit, rollback and get. .Pp The following functions are used for OCTET STRING scalars, either NUL terminated or not: .Bl -tag -width "XXXXXXXXX" .It Fn string_save should be called for SNMP_OP_SET. .Fa value and .Fa ctx are the resp\&.\& arguments to the node callback. .Fa valp is a pointer to the pointer that holds the current value and .Fa req_size should be -1 if any size of the string is acceptable or a number larger or equal zero if the string must have a specific size. The function saves the old value in the scratch area (note, that any initial value must have been allocated by .Xr malloc 3 ) , allocates a new string, copies over the new value, NUL-terminates it and sets the new current value. .It Fn string_commit simply frees the saved old value in the scratch area. .It Fn string_rollback frees the new value, and puts back the old one. .It Fn string_get is used for GET or GETNEXT. The function .It Fn string_get_max can be used instead of .Fn string_get to ensure that the returned string has a certain maximum length. If .Fa len is -1, the length is computed via .Xr strlen 3 from the current string value. If the current value is NULL, a OCTET STRING of zero length is returned. .It Fn string_free must be called if either rollback or commit fails to free the saved old value. .El .Pp The following functions are used to process scalars of type IP-address: .Bl -tag -width "XXXXXXXXX" .It Fn ip_save Saves the current value in the scratch area and sets the new value from .Fa valp . .It Fn ip_commit Does nothing. .It Fn ip_rollback Restores the old IP address from the scratch area. .It Fn ip_get Retrieves the IP current address. .El .Pp The following functions handle OID-typed variables: .Bl -tag -width "XXXXXXXXX" .It Fn oid_save Saves the current value in the scratch area by allocating a .Vt struct asn_oid with .Xr malloc 3 and sets the new value from .Fa oid . .It Fn oid_commit Frees the old value in the scratch area. .It Fn oid_rollback Restores the old OID from the scratch area and frees the old OID. .It Fn oid_get Retrieves the OID .El .Ss TABLE INDEX HANDLING The following functions help in handling table indexes: .Bl -tag -width "XXXXXXXXX" .It Fn index_decode Decodes the index part of the OID. The parameter .Fa oid must be a pointer to the .Va var field of the .Fa value argument of the node callback. The .Fa sub argument must be the index of the start of the index in the OID (this is the .Fa sub argument to the node callback). .Fa code is the index expression (parameter .Fa idx to the node callback). These parameters are followed by parameters depending on the syntax of the index elements as follows: .Bl -tag -width ".It Li OCTET STRING" .It Li INTEGER .Vt int32_t * expected as argument. .It Li COUNTER64 .Vt uint64_t * expected as argument. Note, that this syntax is illegal for indexes. .It Li OCTET STRING A .Vt u_char ** and a .Vt size_t * expected as arguments. A buffer is allocated to hold the decoded string. .It Li OID A .Vt struct asn_oid * is expected as argument. .It Li IP ADDRESS A .Vt u_int8_t * expected as argument that points to a buffer of at least four byte. .It Li COUNTER, GAUGE, TIMETICKS A .Vt u_int32_t expected. .It Li NULL No argument expected. .El .It Fn index_compare compares the current variable with an OID. .Fa oid1 and .Fa sub come from the node callback arguments .Fa value->var and .Fa sub resp. .Fa oid2 is the OID to compare to. The function returns -1, 0, +1 when the variable is lesser, equal, higher to the given OID. .Fa oid2 must contain only the index part of the table column. .It Fn index_compare_off is equivalent to .Fn index_compare except that it takes an additional parameter .Fa off that causes it to ignore the first .Fa off components of both indexes. .It Fn index_append appends OID .Fa src beginning at position .Fa sub to .Fa dst . .It Fn index_append_off appends OID .Fa src beginning at position .Fa off to .Fa dst beginning at position .Fa sub + .Fa off . .El .Sh SEE ALSO .Xr gensnmptree 1 , .Xr bsnmpd 1 , .Xr bsnmpagent 3 , .Xr bsnmpclient 3 , .Xr bsnmplib 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. .Sh AUTHORS .An Hartmut Brandt Aq harti@FreeBSD.org Index: head/lib/libc/locale/isdigit.3 =================================================================== --- head/lib/libc/locale/isdigit.3 (revision 332641) +++ head/lib/libc/locale/isdigit.3 (revision 332642) @@ -1,113 +1,114 @@ .\" Copyright (c) 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" the American National Standards Committee X3, on Information .\" Processing Systems. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)isdigit.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd May 4, 2007 .Dt ISDIGIT 3 .Os .Sh NAME -.Nm isdigit, isnumber +.Nm isdigit , +.Nm isnumber .Nd decimal-digit character test .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In ctype.h .Ft int .Fn isdigit "int c" .Ft int .Fn isnumber "int c" .Ft int .Fn isdigit_l "int c" "locale_t loc" .Ft int .Fn isnumber_l "int c" "locale_t loc" .Sh DESCRIPTION The .Fn isdigit function tests for a decimal digit character. Regardless of locale, this includes the following characters only: .Bl -column \&``0''______ \&``0''______ \&``0''______ \&``0''______ \&``0''______ .It "\&``0''" Ta "``1''" Ta "``2''" Ta "``3''" Ta "``4''" .It "\&``5''" Ta "``6''" Ta "``7''" Ta "``8''" Ta "``9''" .El .Pp The .Fn isnumber function behaves similarly to .Fn isdigit , but may recognize additional characters, depending on the current locale setting. .Pp The value of the argument must be representable as an .Vt "unsigned char" or the value of .Dv EOF . .Pp The _l-suffixed versions take an explicit locale argument, whereas the non-suffixed versions use the current global or per-thread locale. .Sh RETURN VALUES The .Fn isdigit and .Fn isnumber functions return zero if the character tests false and return non-zero if the character tests true. .Sh COMPATIBILITY The .Bx 4.4 extension of accepting arguments outside of the range of the .Vt "unsigned char" type in locales with large character sets is considered obsolete and may not be supported in future releases. The .Fn iswdigit function should be used instead. .Sh SEE ALSO .Xr ctype 3 , .Xr iswdigit 3 , .Xr multibyte 3 , .Xr xlocale 3 , .Xr ascii 7 .Sh STANDARDS The .Fn isdigit function conforms to .St -isoC . The .Fn isdigit_l function conforms to .St -p1003.1-2008 . .Sh HISTORY The .Fn isnumber function appeared in .Bx 4.4 . Index: head/lib/libc/locale/isxdigit.3 =================================================================== --- head/lib/libc/locale/isxdigit.3 (revision 332641) +++ head/lib/libc/locale/isxdigit.3 (revision 332642) @@ -1,101 +1,102 @@ .\" Copyright (c) 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" the American National Standards Committee X3, on Information .\" Processing Systems. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)isxdigit.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd July 17, 2005 .Dt ISXDIGIT 3 .Os .Sh NAME -.Nm isxdigit, ishexnumber +.Nm isxdigit , +.Nm ishexnumber .Nd hexadecimal-digit character test .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In ctype.h .Ft int .Fn isxdigit "int c" .Ft int .Fn ishexnumber "int c" .Sh DESCRIPTION The .Fn isxdigit function tests for any hexadecimal-digit character. Regardless of locale, this includes the following characters only: .Bl -column \&``0''______ \&``0''______ \&``0''______ \&``0''______ \&``0''______ .It "\&``0''" Ta "``1''" Ta "``2''" Ta "``3''" Ta "``4''" .It "\&``5''" Ta "``6''" Ta "``7''" Ta "``8''" Ta "``9''" .It "\&``A''" Ta "``B''" Ta "``C''" Ta "``D''" Ta "``E''" .It "\&``F''" Ta "``a''" Ta "``b''" Ta "``c''" Ta "``d''" .It "\&``e''" Ta "``f''" Ta \& Ta \& Ta \& .El .Pp The .Fn ishexnumber function behaves similarly to .Fn isxdigit , but may recognize additional characters, depending on the current locale setting. .Pp The value of the argument must be representable as an .Vt "unsigned char" or the value of .Dv EOF . .Sh RETURN VALUES The .Fn isxdigit function returns zero if the character tests false and returns non-zero if the character tests true. .Sh COMPATIBILITY The .Bx 4.4 extension of accepting arguments outside of the range of the .Vt "unsigned char" type in locales with large character sets is considered obsolete and may not be supported in future releases. The .Fn iswxdigit function should be used instead. .Sh SEE ALSO .Xr ctype 3 , .Xr iswxdigit 3 , .Xr ascii 7 .Sh STANDARDS The .Fn isxdigit function conforms to .St -isoC . .Sh HISTORY The .Fn ishexnumber function appeared in .Bx 4.4 . Index: head/lib/libc/stdio/printf.3 =================================================================== --- head/lib/libc/stdio/printf.3 (revision 332641) +++ head/lib/libc/stdio/printf.3 (revision 332642) @@ -1,891 +1,901 @@ .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Chris Torek and the American National Standards Committee X3, .\" on Information Processing Systems. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)printf.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd July 30, 2016 .Dt PRINTF 3 .Os .Sh NAME -.Nm printf , fprintf , sprintf , snprintf , asprintf , dprintf , -.Nm vprintf , vfprintf, vsprintf , vsnprintf , vasprintf, vdprintf +.Nm printf , +.Nm fprintf , +.Nm sprintf , +.Nm snprintf , +.Nm asprintf , +.Nm dprintf , +.Nm vprintf , +.Nm vfprintf , +.Nm vsprintf , +.Nm vsnprintf , +.Nm vasprintf , +.Nm vdprintf .Nd formatted output conversion .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In stdio.h .Ft int .Fn printf "const char * restrict format" ... .Ft int .Fn fprintf "FILE * restrict stream" "const char * restrict format" ... .Ft int .Fn sprintf "char * restrict str" "const char * restrict format" ... .Ft int .Fn snprintf "char * restrict str" "size_t size" "const char * restrict format" ... .Ft int .Fn asprintf "char **ret" "const char *format" ... .Ft int .Fn dprintf "int fd" "const char * restrict format" ... .In stdarg.h .Ft int .Fn vprintf "const char * restrict format" "va_list ap" .Ft int .Fn vfprintf "FILE * restrict stream" "const char * restrict format" "va_list ap" .Ft int .Fn vsprintf "char * restrict str" "const char * restrict format" "va_list ap" .Ft int .Fn vsnprintf "char * restrict str" "size_t size" "const char * restrict format" "va_list ap" .Ft int .Fn vasprintf "char **ret" "const char *format" "va_list ap" .Ft int .Fn vdprintf "int fd" "const char * restrict format" "va_list ap" .Sh DESCRIPTION The .Fn printf family of functions produces output according to a .Fa format as described below. The .Fn printf and .Fn vprintf functions write output to .Dv stdout , the standard output stream; .Fn fprintf and .Fn vfprintf write output to the given output .Fa stream ; .Fn dprintf and .Fn vdprintf write output to the given file descriptor; .Fn sprintf , .Fn snprintf , .Fn vsprintf , and .Fn vsnprintf write to the character string .Fa str ; and .Fn asprintf and .Fn vasprintf dynamically allocate a new string with .Xr malloc 3 . .Pp These functions write the output under the control of a .Fa format string that specifies how subsequent arguments (or arguments accessed via the variable-length argument facilities of .Xr stdarg 3 ) are converted for output. .Pp The .Fn asprintf and .Fn vasprintf functions set .Fa *ret to be a pointer to a buffer sufficiently large to hold the formatted string. This pointer should be passed to .Xr free 3 to release the allocated storage when it is no longer needed. If sufficient space cannot be allocated, .Fn asprintf and .Fn vasprintf will return \-1 and set .Fa ret to be a .Dv NULL pointer. .Pp The .Fn snprintf and .Fn vsnprintf functions will write at most .Fa size Ns \-1 of the characters printed into the output string (the .Fa size Ns 'th character then gets the terminating .Ql \e0 ) ; if the return value is greater than or equal to the .Fa size argument, the string was too short and some of the printed characters were discarded. The output is always null-terminated, unless .Fa size is 0. .Pp The .Fn sprintf and .Fn vsprintf functions effectively assume a .Fa size of .Dv INT_MAX + 1. .Pp The format string is composed of zero or more directives: ordinary .\" multibyte characters (not .Cm % ) , which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the .Cm % character. The arguments must correspond properly (after type promotion) with the conversion specifier. After the .Cm % , the following appear in sequence: .Bl -bullet .It An optional field, consisting of a decimal digit string followed by a .Cm $ , specifying the next argument to access. If this field is not provided, the argument following the last argument accessed will be used. Arguments are numbered starting at .Cm 1 . If unaccessed arguments in the format string are interspersed with ones that are accessed the results will be indeterminate. .It Zero or more of the following flags: .Bl -tag -width ".So \ Sc (space)" .It Sq Cm # The value should be converted to an .Dq alternate form . For .Cm c , d , i , n , p , s , and .Cm u conversions, this option has no effect. For .Cm o conversions, the precision of the number is increased to force the first character of the output string to a zero. For .Cm x and .Cm X conversions, a non-zero result has the string .Ql 0x (or .Ql 0X for .Cm X conversions) prepended to it. For .Cm a , A , e , E , f , F , g , and .Cm G conversions, the result will always contain a decimal point, even if no digits follow it (normally, a decimal point appears in the results of those conversions only if a digit follows). For .Cm g and .Cm G conversions, trailing zeros are not removed from the result as they would otherwise be. .It So Cm 0 Sc (zero) Zero padding. For all conversions except .Cm n , the converted value is padded on the left with zeros rather than blanks. If a precision is given with a numeric conversion .Cm ( d , i , o , u , i , x , and .Cm X ) , the .Cm 0 flag is ignored. .It Sq Cm \- A negative field width flag; the converted value is to be left adjusted on the field boundary. Except for .Cm n conversions, the converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A .Cm \- overrides a .Cm 0 if both are given. .It So "\ " Sc (space) A blank should be left before a positive number produced by a signed conversion .Cm ( a , A , d , e , E , f , F , g , G , or .Cm i ) . .It Sq Cm + A sign must always be placed before a number produced by a signed conversion. A .Cm + overrides a space if both are used. .It So "'" Sc (apostrophe) Decimal conversions .Cm ( d , u , or .Cm i ) or the integral portion of a floating point conversion .Cm ( f or .Cm F ) should be grouped and separated by thousands using the non-monetary separator returned by .Xr localeconv 3 . .El .It An optional decimal digit string specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given) to fill out the field width. .It An optional precision, in the form of a period .Cm \&. followed by an optional digit string. If the digit string is omitted, the precision is taken as zero. This gives the minimum number of digits to appear for .Cm d , i , o , u , x , and .Cm X conversions, the number of digits to appear after the decimal-point for .Cm a , A , e , E , f , and .Cm F conversions, the maximum number of significant digits for .Cm g and .Cm G conversions, or the maximum number of characters to be printed from a string for .Cm s conversions. .It An optional length modifier, that specifies the size of the argument. The following length modifiers are valid for the .Cm d , i , n , o , u , x , or .Cm X conversion: .Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *" .It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n .It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *" .It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *" .It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *" .It Cm ll No (ell ell) Ta Vt "long long" Ta Vt "unsigned long long" Ta Vt "long long *" .It Cm j Ta Vt intmax_t Ta Vt uintmax_t Ta Vt "intmax_t *" .It Cm t Ta Vt ptrdiff_t Ta (see note) Ta Vt "ptrdiff_t *" .It Cm z Ta (see note) Ta Vt size_t Ta (see note) .It Cm q Em (deprecated) Ta Vt quad_t Ta Vt u_quad_t Ta Vt "quad_t *" .El .Pp Note: the .Cm t modifier, when applied to a .Cm o , u , x , or .Cm X conversion, indicates that the argument is of an unsigned type equivalent in size to a .Vt ptrdiff_t . The .Cm z modifier, when applied to a .Cm d or .Cm i conversion, indicates that the argument is of a signed type equivalent in size to a .Vt size_t . Similarly, when applied to an .Cm n conversion, it indicates that the argument is a pointer to a signed type equivalent in size to a .Vt size_t . .Pp The following length modifier is valid for the .Cm a , A , e , E , f , F , g , or .Cm G conversion: .Bl -column ".Sy Modifier" ".Cm a , A , e , E , f , F , g , G" .It Sy Modifier Ta Cm a , A , e , E , f , F , g , G .It Cm l No (ell) Ta Vt double (ignored, same behavior as without it) .It Cm L Ta Vt "long double" .El .Pp The following length modifier is valid for the .Cm c or .Cm s conversion: .Bl -column ".Sy Modifier" ".Vt wint_t" ".Vt wchar_t *" .It Sy Modifier Ta Cm c Ta Cm s .It Cm l No (ell) Ta Vt wint_t Ta Vt "wchar_t *" .El .It A character that specifies the type of conversion to be applied. .El .Pp A field width or precision, or both, may be indicated by an asterisk .Ql * or an asterisk followed by one or more decimal digits and a .Ql $ instead of a digit string. In this case, an .Vt int argument supplies the field width or precision. A negative field width is treated as a left adjustment flag followed by a positive field width; a negative precision is treated as though it were missing. If a single format directive mixes positional .Pq Li nn$ and non-positional arguments, the results are undefined. .Pp The conversion specifiers and their meanings are: .Bl -tag -width ".Cm diouxX" .It Cm diouxX The .Vt int (or appropriate variant) argument is converted to signed decimal .Cm ( d and .Cm i ) , unsigned octal .Pq Cm o , unsigned decimal .Pq Cm u , or unsigned hexadecimal .Cm ( x and .Cm X ) notation. The letters .Dq Li abcdef are used for .Cm x conversions; the letters .Dq Li ABCDEF are used for .Cm X conversions. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. .It Cm DOU The .Vt "long int" argument is converted to signed decimal, unsigned octal, or unsigned decimal, as if the format had been .Cm ld , lo , or .Cm lu respectively. These conversion characters are deprecated, and will eventually disappear. .It Cm eE The .Vt double argument is rounded and converted in the style .Sm off .Oo \- Oc Ar d Li \&. Ar ddd Li e \(+- Ar dd .Sm on where there is one digit before the decimal-point character and the number of digits after it is equal to the precision; if the precision is missing, it is taken as 6; if the precision is zero, no decimal-point character appears. An .Cm E conversion uses the letter .Ql E (rather than .Ql e ) to introduce the exponent. The exponent always contains at least two digits; if the value is zero, the exponent is 00. .Pp For .Cm a , A , e , E , f , F , g , and .Cm G conversions, positive and negative infinity are represented as .Li inf and .Li -inf respectively when using the lowercase conversion character, and .Li INF and .Li -INF respectively when using the uppercase conversion character. Similarly, NaN is represented as .Li nan when using the lowercase conversion, and .Li NAN when using the uppercase conversion. .It Cm fF The .Vt double argument is rounded and converted to decimal notation in the style .Sm off .Oo \- Oc Ar ddd Li \&. Ar ddd , .Sm on where the number of digits after the decimal-point character is equal to the precision specification. If the precision is missing, it is taken as 6; if the precision is explicitly zero, no decimal-point character appears. If a decimal point appears, at least one digit appears before it. .It Cm gG The .Vt double argument is converted in style .Cm f or .Cm e (or .Cm F or .Cm E for .Cm G conversions). The precision specifies the number of significant digits. If the precision is missing, 6 digits are given; if the precision is zero, it is treated as 1. Style .Cm e is used if the exponent from its conversion is less than \-4 or greater than or equal to the precision. Trailing zeros are removed from the fractional part of the result; a decimal point appears only if it is followed by at least one digit. .It Cm aA The .Vt double argument is rounded and converted to hexadecimal notation in the style .Sm off .Oo \- Oc Li 0x Ar h Li \&. Ar hhhp Oo \(+- Oc Ar d , .Sm on where the number of digits after the hexadecimal-point character is equal to the precision specification. If the precision is missing, it is taken as enough to represent the floating-point number exactly, and no rounding occurs. If the precision is zero, no hexadecimal-point character appears. The .Cm p is a literal character .Ql p , and the exponent consists of a positive or negative sign followed by a decimal number representing an exponent of 2. The .Cm A conversion uses the prefix .Dq Li 0X (rather than .Dq Li 0x ) , the letters .Dq Li ABCDEF (rather than .Dq Li abcdef ) to represent the hex digits, and the letter .Ql P (rather than .Ql p ) to separate the mantissa and exponent. .Pp Note that there may be multiple valid ways to represent floating-point numbers in this hexadecimal format. For example, .Li 0x1.92p+1 , 0x3.24p+0 , 0x6.48p-1 , and .Li 0xc.9p-2 are all equivalent. .Fx 8.0 and later always prints finite non-zero numbers using .Ql 1 as the digit before the hexadecimal point. Zeroes are always represented with a mantissa of 0 (preceded by a .Ql - if appropriate) and an exponent of .Li +0 . .It Cm C Treated as .Cm c with the .Cm l (ell) modifier. .It Cm c The .Vt int argument is converted to an .Vt "unsigned char" , and the resulting character is written. .Pp If the .Cm l (ell) modifier is used, the .Vt wint_t argument shall be converted to a .Vt wchar_t , and the (potentially multi-byte) sequence representing the single wide character is written, including any shift sequences. If a shift sequence is used, the shift state is also restored to the original state after the character. .It Cm S Treated as .Cm s with the .Cm l (ell) modifier. .It Cm s The .Vt "char *" argument is expected to be a pointer to an array of character type (pointer to a string). Characters from the array are written up to (but not including) a terminating .Dv NUL character; if a precision is specified, no more than the number specified are written. If a precision is given, no null character need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating .Dv NUL character. .Pp If the .Cm l (ell) modifier is used, the .Vt "wchar_t *" argument is expected to be a pointer to an array of wide characters (pointer to a wide string). For each wide character in the string, the (potentially multi-byte) sequence representing the wide character is written, including any shift sequences. If any shift sequence is used, the shift state is also restored to the original state after the string. Wide characters from the array are written up to (but not including) a terminating wide .Dv NUL character; if a precision is specified, no more than the number of bytes specified are written (including shift sequences). Partial characters are never written. If a precision is given, no null character need be present; if the precision is not specified, or is greater than the number of bytes required to render the multibyte representation of the string, the array must contain a terminating wide .Dv NUL character. .It Cm p The .Vt "void *" pointer argument is printed in hexadecimal (as if by .Ql %#x or .Ql %#lx ) . .It Cm n The number of characters written so far is stored into the integer indicated by the .Vt "int *" (or variant) pointer argument. No argument is converted. .It Cm % A .Ql % is written. No argument is converted. The complete conversion specification is .Ql %% . .El .Pp The decimal point character is defined in the program's locale (category .Dv LC_NUMERIC ) . .Pp In no case does a non-existent or small field width cause truncation of a numeric field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result. .Sh RETURN VALUES These functions return the number of characters printed (not including the trailing .Ql \e0 used to end output to strings), except for .Fn snprintf and .Fn vsnprintf , which return the number of characters that would have been printed if the .Fa size were unlimited (again, not including the final .Ql \e0 ) . These functions return a negative value if an error occurs. .Sh EXAMPLES To print a date and time in the form .Dq Li "Sunday, July 3, 10:02" , where .Fa weekday and .Fa month are pointers to strings: .Bd -literal -offset indent #include fprintf(stdout, "%s, %s %d, %.2d:%.2d\en", weekday, month, day, hour, min); .Ed .Pp To print \*(Pi to five decimal places: .Bd -literal -offset indent #include #include fprintf(stdout, "pi = %.5f\en", 4 * atan(1.0)); .Ed .Pp To allocate a 128 byte string and print into it: .Bd -literal -offset indent #include #include #include char *newfmt(const char *fmt, ...) { char *p; va_list ap; if ((p = malloc(128)) == NULL) return (NULL); va_start(ap, fmt); (void) vsnprintf(p, 128, fmt, ap); va_end(ap); return (p); } .Ed .Sh COMPATIBILITY The conversion formats .Cm \&%D , \&%O , and .Cm \&%U are not standard and are provided only for backward compatibility. The effect of padding the .Cm %p format with zeros (either by the .Cm 0 flag or by specifying a precision), and the benign effect (i.e., none) of the .Cm # flag on .Cm %n and .Cm %p conversions, as well as other nonsensical combinations such as .Cm %Ld , are not standard; such combinations should be avoided. .Sh ERRORS In addition to the errors documented for the .Xr write 2 system call, the .Fn printf family of functions may fail if: .Bl -tag -width Er .It Bq Er EILSEQ An invalid wide character code was encountered. .It Bq Er ENOMEM Insufficient storage space is available. .It Bq Er EOVERFLOW The .Fa size argument exceeds .Dv INT_MAX + 1 , or the return value would be too large to be represented by an .Vt int . .El .Sh SEE ALSO .Xr printf 1 , .Xr fmtcheck 3 , .Xr scanf 3 , .Xr setlocale 3 , .Xr wprintf 3 .Sh STANDARDS Subject to the caveats noted in the .Sx BUGS section below, the .Fn fprintf , .Fn printf , .Fn sprintf , .Fn vprintf , .Fn vfprintf , and .Fn vsprintf functions conform to .St -ansiC and .St -isoC-99 . With the same reservation, the .Fn snprintf and .Fn vsnprintf functions conform to .St -isoC-99 , while .Fn dprintf and .Fn vdprintf conform to .St -p1003.1-2008 . .Sh HISTORY The functions .Fn asprintf and .Fn vasprintf first appeared in the .Tn GNU C library. These were implemented by .An Peter Wemm Aq Mt peter@FreeBSD.org in .Fx 2.2 , but were later replaced with a different implementation from .Ox 2.3 by .An Todd C. Miller Aq Mt Todd.Miller@courtesan.com . The .Fn dprintf and .Fn vdprintf functions were added in .Fx 8.0 . .Sh BUGS The .Nm family of functions do not correctly handle multibyte characters in the .Fa format argument. .Sh SECURITY CONSIDERATIONS The .Fn sprintf and .Fn vsprintf functions are easily misused in a manner which enables malicious users to arbitrarily change a running program's functionality through a buffer overflow attack. Because .Fn sprintf and .Fn vsprintf assume an infinitely long string, callers must be careful not to overflow the actual space; this is often hard to assure. For safety, programmers should use the .Fn snprintf interface instead. For example: .Bd -literal void foo(const char *arbitrary_string, const char *and_another) { char onstack[8]; #ifdef BAD /* * This first sprintf is bad behavior. Do not use sprintf! */ sprintf(onstack, "%s, %s", arbitrary_string, and_another); #else /* * The following two lines demonstrate better use of * snprintf(). */ snprintf(onstack, sizeof(onstack), "%s, %s", arbitrary_string, and_another); #endif } .Ed .Pp The .Fn printf and .Fn sprintf family of functions are also easily misused in a manner allowing malicious users to arbitrarily change a running program's functionality by either causing the program to print potentially sensitive data .Dq "left on the stack" , or causing it to generate a memory fault or bus error by dereferencing an invalid pointer. .Pp .Cm %n can be used to write arbitrary data to potentially carefully-selected addresses. Programmers are therefore strongly advised to never pass untrusted strings as the .Fa format argument, as an attacker can put format specifiers in the string to mangle your stack, leading to a possible security hole. This holds true even if the string was built using a function like .Fn snprintf , as the resulting string may still contain user-supplied conversion specifiers for later interpolation by .Fn printf . .Pp Always use the proper secure idiom: .Pp .Dl "snprintf(buffer, sizeof(buffer), \*q%s\*q, string);" Index: head/lib/libc/stdlib/qsort.3 =================================================================== --- head/lib/libc/stdlib/qsort.3 (revision 332641) +++ head/lib/libc/stdlib/qsort.3 (revision 332642) @@ -1,366 +1,372 @@ .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" the American National Standards Committee X3, on Information .\" Processing Systems. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)qsort.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd February 20, 2013 .Dt QSORT 3 .Os .Sh NAME -.Nm qsort , qsort_b , qsort_r , heapsort , heapsort_b , mergesort, mergesort_b +.Nm qsort , +.Nm qsort_b , +.Nm qsort_r , +.Nm heapsort , +.Nm heapsort_b , +.Nm mergesort , +.Nm mergesort_b .Nd sort functions .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In stdlib.h .Ft void .Fo qsort .Fa "void *base" .Fa "size_t nmemb" .Fa "size_t size" .Fa "int \*[lp]*compar\*[rp]\*[lp]const void *, const void *\*[rp]" .Fc .Ft void .Fo qsort_b .Fa "void *base" .Fa "size_t nmemb" .Fa "size_t size" .Fa "int \*[lp]^compar\*[rp]\*[lp]const void *, const void *\*[rp]" .Fc .Ft void .Fo qsort_r .Fa "void *base" .Fa "size_t nmemb" .Fa "size_t size" .Fa "void *thunk" .Fa "int \*[lp]*compar\*[rp]\*[lp]void *, const void *, const void *\*[rp]" .Fc .Ft int .Fo heapsort .Fa "void *base" .Fa "size_t nmemb" .Fa "size_t size" .Fa "int \*[lp]*compar\*[rp]\*[lp]const void *, const void *\*[rp]" .Fc .Ft int .Fo heapsort_b .Fa "void *base" .Fa "size_t nmemb" .Fa "size_t size" .Fa "int \*[lp]^compar\*[rp]\*[lp]const void *, const void *\*[rp]" .Fc .Ft int .Fo mergesort .Fa "void *base" .Fa "size_t nmemb" .Fa "size_t size" .Fa "int \*[lp]*compar\*[rp]\*[lp]const void *, const void *\*[rp]" .Fc .Ft int .Fo mergesort_b .Fa "void *base" .Fa "size_t nmemb" .Fa "size_t size" .Fa "int \*[lp]^compar\*[rp]\*[lp]const void *, const void *\*[rp]" .Fc .Sh DESCRIPTION The .Fn qsort function is a modified partition-exchange sort, or quicksort. The .Fn heapsort function is a modified selection sort. The .Fn mergesort function is a modified merge sort with exponential search intended for sorting data with pre-existing order. .Pp The .Fn qsort and .Fn heapsort functions sort an array of .Fa nmemb objects, the initial member of which is pointed to by .Fa base . The size of each object is specified by .Fa size . The .Fn mergesort function behaves similarly, but .Em requires that .Fa size be greater than .Dq "sizeof(void *) / 2" . .Pp The contents of the array .Fa base are sorted in ascending order according to a comparison function pointed to by .Fa compar , which requires two arguments pointing to the objects being compared. .Pp The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second. .Pp The .Fn qsort_r function behaves identically to .Fn qsort , except that it takes an additional argument, .Fa thunk , which is passed unchanged as the first argument to function pointed to .Fa compar . This allows the comparison function to access additional data without using global variables, and thus .Fn qsort_r is suitable for use in functions which must be reentrant. The .Fn qsort_b function behaves identically to .Fn qsort , except that it takes a block, rather than a function pointer. .Pp The algorithms implemented by .Fn qsort , .Fn qsort_r , and .Fn heapsort are .Em not stable, that is, if two members compare as equal, their order in the sorted array is undefined. The .Fn heapsort_b function behaves identically to .Fn heapsort , except that it takes a block, rather than a function pointer. The .Fn mergesort algorithm is stable. The .Fn mergesort_b function behaves identically to .Fn mergesort , except that it takes a block, rather than a function pointer. .Pp The .Fn qsort and .Fn qsort_r functions are an implementation of C.A.R. Hoare's .Dq quicksort algorithm, a variant of partition-exchange sorting; in particular, see .An D.E. Knuth Ns 's .%T "Algorithm Q" . .Sy Quicksort takes O N lg N average time. This implementation uses median selection to avoid its O N**2 worst-case behavior. .Pp The .Fn heapsort function is an implementation of .An "J.W.J. William" Ns 's .Dq heapsort algorithm, a variant of selection sorting; in particular, see .An "D.E. Knuth" Ns 's .%T "Algorithm H" . .Sy Heapsort takes O N lg N worst-case time. Its .Em only advantage over .Fn qsort is that it uses almost no additional memory; while .Fn qsort does not allocate memory, it is implemented using recursion. .Pp The function .Fn mergesort requires additional memory of size .Fa nmemb * .Fa size bytes; it should be used only when space is not at a premium. 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 Normally, .Fn qsort is faster than .Fn mergesort is faster than .Fn heapsort . Memory availability and pre-existing order in the data can make this untrue. .Sh RETURN VALUES The .Fn qsort and .Fn qsort_r functions return no value. .Pp .Rv -std heapsort mergesort .Sh EXAMPLES A sample program that sorts an array of .Vt int values in place using .Fn qsort , and then prints the sorted array to standard output is: .Bd -literal #include #include /* * Custom comparison function that compares 'int' values through pointers * passed by qsort(3). */ static int int_compare(const void *p1, const void *p2) { int left = *(const int *)p1; int right = *(const int *)p2; return ((left > right) - (left < right)); } /* * Sort an array of 'int' values and print it to standard output. */ int main(void) { int int_array[] = { 4, 5, 9, 3, 0, 1, 7, 2, 8, 6 }; size_t array_size = sizeof(int_array) / sizeof(int_array[0]); size_t k; qsort(&int_array, array_size, sizeof(int_array[0]), int_compare); for (k = 0; k < array_size; k++) printf(" %d", int_array[k]); puts(""); return (EXIT_SUCCESS); } .Ed .Sh COMPATIBILITY Previous versions of .Fn qsort did not permit the comparison routine itself to call .Fn qsort 3 . This is no longer true. .Sh ERRORS The .Fn heapsort and .Fn mergesort functions succeed unless: .Bl -tag -width Er .It Bq Er EINVAL The .Fa size argument is zero, or, the .Fa size argument to .Fn mergesort is less than .Dq "sizeof(void *) / 2" . .It Bq Er ENOMEM The .Fn heapsort or .Fn mergesort functions were unable to allocate memory. .El .Sh SEE ALSO .Xr sort 1 , .Xr radixsort 3 .Rs .%A Hoare, C.A.R. .%D 1962 .%T "Quicksort" .%J "The Computer Journal" .%V 5:1 .%P pp. 10-15 .Re .Rs .%A Williams, J.W.J .%D 1964 .%T "Heapsort" .%J "Communications of the ACM" .%V 7:1 .%P pp. 347-348 .Re .Rs .%A Knuth, D.E. .%D 1968 .%B "The Art of Computer Programming" .%V Vol. 3 .%T "Sorting and Searching" .%P pp. 114-123, 145-149 .Re .Rs .%A McIlroy, P.M. .%T "Optimistic Sorting and Information Theoretic Complexity" .%J "Fourth Annual ACM-SIAM Symposium on Discrete Algorithms" .%V January 1992 .Re .Rs .%A Bentley, J.L. .%A McIlroy, M.D. .%T "Engineering a Sort Function" .%J "Software--Practice and Experience" .%V Vol. 23(11) .%P pp. 1249-1265 .%D November\ 1993 .Re .Sh STANDARDS The .Fn qsort function conforms to .St -isoC . .Sh HISTORY The variants of these functions that take blocks as arguments first appeared in Mac OS X. This implementation was created by David Chisnall. Index: head/lib/libc/string/strcpy.3 =================================================================== --- head/lib/libc/string/strcpy.3 (revision 332641) +++ head/lib/libc/string/strcpy.3 (revision 332642) @@ -1,222 +1,225 @@ .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Chris Torek and the American National Standards Committee X3, .\" on Information Processing Systems. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)strcpy.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd February 28, 2009 .Dt STRCPY 3 .Os .Sh NAME -.Nm stpcpy, stpncpy, strcpy , strncpy +.Nm stpcpy , +.Nm stpncpy , +.Nm strcpy , +.Nm strncpy .Nd copy strings .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In string.h .Ft char * .Fn stpcpy "char * restrict dst" "const char * restrict src" .Ft char * .Fn stpncpy "char * restrict dst" "const char * restrict src" "size_t len" .Ft char * .Fn strcpy "char * restrict dst" "const char * restrict src" .Ft char * .Fn strncpy "char * restrict dst" "const char * restrict src" "size_t len" .Sh DESCRIPTION The .Fn stpcpy and .Fn strcpy functions copy the string .Fa src to .Fa dst (including the terminating .Ql \e0 character.) If .Fa src and .Fa dst overlap, the results are undefined. .Pp The .Fn stpncpy and .Fn strncpy functions copy at most .Fa len characters from .Fa src into .Fa dst . If .Fa src is less than .Fa len characters long, the remainder of .Fa dst is filled with .Ql \e0 characters. Otherwise, .Fa dst is .Em not terminated. If .Fa src and .Fa dst overlap, the results are undefined. .Sh RETURN VALUES The .Fn strcpy and .Fn strncpy functions return .Fa dst . The .Fn stpcpy and .Fn stpncpy functions return a pointer to the terminating .Ql \e0 character of .Fa dst . If .Fn stpncpy does not terminate .Fa dst with a .Dv NUL character, it instead returns a pointer to .Li dst[n] (which does not necessarily refer to a valid memory location.) .Sh EXAMPLES The following sets .Va chararray to .Dq Li abc\e0\e0\e0 : .Bd -literal -offset indent char chararray[6]; (void)strncpy(chararray, "abc", sizeof(chararray)); .Ed .Pp The following sets .Va chararray to .Dq Li abcdef : .Bd -literal -offset indent char chararray[6]; (void)strncpy(chararray, "abcdefgh", sizeof(chararray)); .Ed .Pp Note that it does .Em not .Tn NUL terminate .Va chararray because the length of the source string is greater than or equal to the length argument. .Pp The following copies as many characters from .Va input to .Va buf as will fit and .Tn NUL terminates the result. Because .Fn strncpy does .Em not guarantee to .Tn NUL terminate the string itself, this must be done explicitly. .Bd -literal -offset indent char buf[1024]; (void)strncpy(buf, input, sizeof(buf) - 1); buf[sizeof(buf) - 1] = '\e0'; .Ed .Pp This could be better achieved using .Xr strlcpy 3 , as shown in the following example: .Pp .Dl "(void)strlcpy(buf, input, sizeof(buf));" .Pp Note that because .Xr strlcpy 3 is not defined in any standards, it should only be used when portability is not a concern. .Sh SEE ALSO .Xr bcopy 3 , .Xr memccpy 3 , .Xr memcpy 3 , .Xr memmove 3 , .Xr strlcpy 3 , .Xr wcscpy 3 .Sh STANDARDS The .Fn strcpy and .Fn strncpy functions conform to .St -isoC . The .Fn stpcpy and .Fn stpncpy functions conform to .St -p1003.1-2008 . .Sh HISTORY The .Fn stpcpy function first appeared in .Fx 4.4 , and .Fn stpncpy was added in .Fx 8.0 . .Sh SECURITY CONSIDERATIONS The .Fn strcpy function is easily misused in a manner which enables malicious users to arbitrarily change a running program's functionality through a buffer overflow attack. Index: head/lib/libc/string/strlen.3 =================================================================== --- head/lib/libc/string/strlen.3 (revision 332641) +++ head/lib/libc/string/strlen.3 (revision 332642) @@ -1,92 +1,93 @@ .\" Copyright (c) 1990, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" Chris Torek and the American National Standards Committee X3, .\" on Information Processing Systems. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)strlen.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd February 28, 2009 .Dt STRLEN 3 .Os .Sh NAME -.Nm strlen, strnlen +.Nm strlen , +.Nm strnlen .Nd find length of string .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In string.h .Ft size_t .Fn strlen "const char *s" .Ft size_t .Fn strnlen "const char *s" "size_t maxlen" .Sh DESCRIPTION The .Fn strlen function computes the length of the string .Fa s . The .Fn strnlen function attempts to compute the length of .Fa s , but never scans beyond the first .Fa maxlen bytes of .Fa s . .Sh RETURN VALUES The .Fn strlen function returns the number of characters that precede the terminating .Dv NUL character. The .Fn strnlen function returns either the same result as .Fn strlen or .Fa maxlen , whichever is smaller. .Sh SEE ALSO .Xr string 3 , .Xr wcslen 3 , .Xr wcswidth 3 .Sh STANDARDS The .Fn strlen function conforms to .St -isoC . The .Fn strnlen function conforms to .St -p1003.1-2008 . Index: head/lib/libc/sys/fsync.2 =================================================================== --- head/lib/libc/sys/fsync.2 (revision 332641) +++ head/lib/libc/sys/fsync.2 (revision 332642) @@ -1,131 +1,132 @@ .\" Copyright (c) 1983, 1993 .\" The Regents of the University of California. All rights reserved. .\" Copyright (c) 2016 The FreeBSD Foundation, Inc. .\" All rights reserved. .\" .\" Parts of this documentation were written by .\" Konstantin Belousov under sponsorship .\" from the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" @(#)fsync.2 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" .Dd February 6, 2018 .Dt FSYNC 2 .Os .Sh NAME -.Nm fdatasync, fsync +.Nm fdatasync , +.Nm fsync .Nd "synchronise changes to a file" .Sh LIBRARY .Lb libc .Sh SYNOPSIS .In unistd.h .Ft int .Fn fdatasync "int fd" .Ft int .Fn fsync "int fd" .Sh DESCRIPTION The .Fn fsync system call causes all modified data and attributes of the file referenced by the file descriptor .Fa fd to be moved to a permanent storage device. This normally results in all in-core modified copies of buffers for the associated file to be written to a disk. .Pp The .Fn fdatasync system call causes all modified data of .Fa fd to be moved to a permanent storage device. Unlike .Fn fsync , the system call does not guarantee that file attributes or metadata necessary to access the file are committed to the permanent storage. .Pp The .Fn fsync system call should be used by programs that require a file to be in a known state, for example, in building a simple transaction facility. If the file metadata has already been committed, using .Fn fdatasync can be more efficient than .Fn fsync . .Pp Both .Fn fdatasync and .Fn fsync calls are cancellation points. .Sh RETURN VALUES .Rv -std fsync .Sh ERRORS The .Fn fsync and .Fn fdatasync calls fail if: .Bl -tag -width Er .It Bq Er EBADF The .Fa fd argument is not a valid descriptor. .It Bq Er EINVAL The .Fa fd argument refers to a socket, not to a file. .It Bq Er EIO An I/O error occurred while reading from or writing to the file system. .El .Sh SEE ALSO .Xr fsync 1 , .Xr sync 2 , .Xr syncer 4 , .Xr sync 8 .Sh HISTORY The .Fn fsync system call appeared in .Bx 4.2 . The .Fn fdatasync system call appeared in .Fx 11.1 . .Sh BUGS The .Fn fdatasync system call currently does not guarantee that enqueued .Xr aio 4 requests for the file referenced by .Fa fd are completed before the syscall returns. Index: head/lib/libufs/ufs_disk_close.3 =================================================================== --- head/lib/libufs/ufs_disk_close.3 (revision 332641) +++ head/lib/libufs/ufs_disk_close.3 (revision 332642) @@ -1,112 +1,115 @@ .\" Author: Juli Mallett .\" Date: June 04, 2003 .\" Description: .\" Manual page for libufs functions: .\" ufs_disk_close(3) .\" ufs_disk_fillout(3) .\" ufs_disk_fillout_blank(3) .\" ufs_disk_write(3) .\" .\" This file is in the public domain. .\" .\" $FreeBSD$ .\" .Dd June 4, 2003 .Dt UFS_DISK_CLOSE 3 .Os .Sh NAME -.Nm ufs_disk_close , ufs_disk_fillout , ufs_disk_fillout_blank, ufs_disk_write +.Nm ufs_disk_close , +.Nm ufs_disk_fillout , +.Nm ufs_disk_fillout_blank , +.Nm ufs_disk_write .Nd open and close userland UFS disks .Sh LIBRARY .Lb libufs .Sh SYNOPSIS .In sys/param.h .In sys/mount.h .In ufs/ufs/ufsmount.h .In ufs/ufs/dinode.h .In ufs/ffs/fs.h .In libufs.h .Ft int .Fn ufs_disk_close "struct uufsd *disk" .Ft int .Fn ufs_disk_fillout "struct uufsd *disk" "const char *name" .Ft int .Fn ufs_disk_fillout_blank "struct uufsd *disk" "const char *name" .Ft int .Fn ufs_disk_write "struct uufsd *disk" .Sh DESCRIPTION The .Fn ufs_disk_close function closes a disk and frees internal memory related to it. It does not free the .Fa disk structure. .Pp The .Fn ufs_disk_fillout and .Fn ufs_disk_fillout_blank functions open a disk specified by .Fa name and populate the structure pointed to by .Fa disk . The disk is opened read-only. The specified .Fa name may be either a mountpoint, a device name or a filesystem image. The .Fn ufs_disk_fillout function assumes there is a valid superblock and will fail if not, whereas the .Fn ufs_disk_fillout_blank function makes no assumptions of that sort. .Pp The .Fn ufs_disk_write function attempts to re-open a disk as writable if it is not currently. .Sh ERRORS The function .Fn ufs_disk_close has no failure points. .Pp The function .Fn ufs_disk_fillout may fail for any of the reasons .Fn ufs_disk_fillout_blank might, as well as for any reason .Xr sbread 3 might. .Pp The .Fn ufs_disk_fillout_blank may fail and set .Va errno for any of the errors specified for the library functions .Xr open 2 , .Xr strdup 3 . Additionally, it may follow the .Xr libufs 3 error methodologies in situations where no device could be found to open. .Pp The function .Fn ufs_disk_write may fail and set .Va errno for any of the errors specified for the library functions .Xr open 2 and .Xr stat 2 . Namely, it will fail if the disk in question may not be written to. .Sh SEE ALSO .Xr open 2 , .Xr getfsfile 3 , .Xr libufs 3 , .Xr sbread 3 .Sh HISTORY These functions first appeared as part of .Xr libufs 3 in .Fx 5.0 . .Sh AUTHORS .An Juli Mallett Aq Mt jmallett@FreeBSD.org Index: head/share/man/man7/c99.7 =================================================================== --- head/share/man/man7/c99.7 (revision 332641) +++ head/share/man/man7/c99.7 (revision 332642) @@ -1,183 +1,187 @@ .\" Copyright (C) 2007, 2010 Gabor Kovesdan. 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 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 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 30, 2011 .Dt C 7 .Os .Sh NAME -.Nm c, c78, c89, c90, c99 +.Nm c , +.Nm c78 , +.Nm c89 , +.Nm c90 , +.Nm c99 .Nd The C programming language .Sh DESCRIPTION C is a general purpose programming language, which has a strong connection with the UNIX operating system and its derivatives, since the vast majority of those systems were written in the C language. The C language contains some basic ideas from the BCPL language through the B language written by Ken Thompson in 1970 for the DEC PDP-7 machines. The development of the UNIX operating system was started on a PDP-7 machine in assembly language, but it made very difficult to port the existing code to other systems. .Pp In 1972 Dennis M. Ritchie worked out the C programming language for further development of the UNIX operating system. The idea was to implement only the C compiler for different platforms, and implement most part of the operating system in the new programming language to simplify the portability between different architectures. It follows that C is very eligible for (but not limited to) writing operating systems and low-level applications. .Pp The C language did not have a specification or standardized version for a long time. It went through a lot of changes and improvements for ages. In 1978, Brian W. Kernighan and Dennis M. Ritchie published the first book about C under the title "The C Programming Language". We can think of this book as the first specification of the language. This version is often referred as K&R C after the names of the authors. Sometimes it is referred as C78, as well, after the publishing year of the first edition of the book. .Pp It is important to notice, that the instruction set of the language is limited to the most fundamental elements for simplicity. Handling of the standard I/O and such common functions are implemented in the libraries shipped with the compiler. As these functions are also widely used, it was demanded to include into the description what requisites the library should conform to, not just strictly the language itself. Accordingly, the aforementioned standards cover the library elements, as well. The elements of this standard library is still not enough for more complicated tasks. In this case the provided system calls of the given operating system can be used. To not lose the portability by using these system calls, the POSIX (Portable Operating System Interface) standard evolved. It describes what functions should be available to keep portability. Note, that POSIX is not a C standard, but an operating system standard and thus is beyond the scope of this manual. The standards discussed below are all C standards and only cover the C programming language and the accompanying library. .Pp After the publication of the book mentioned before, the American National Standards Institute (ANSI) started to work on standardizing the language, and they announced ANSI X3.159-1989 in 1989. It is usually referred as ANSI C or C89. The main difference in this standard were the function prototypes, which is a new way of declaring functions. With the old-style function declarations, the compiler was unable to check the sanity of the actual parameters at a function call. The old syntax was highly error-prone because incompatible parameters were hard to detect in the program code and the problem only showed up at run-time. .Pp In 1990, the International Organization for Standardization (ISO) adopted the ANSI standard as ISO/IEC 9899:1990 in 1990. This is also referred as ISO C or C90. It only contains negligible minor modifications against ANSI C, so the two standards often considered to be fully equivalent. This was a very important milestone in the history of the C language, but the development of the language did not stop. .Pp The ISO C standard was later extended with an amendment as ISO/IEC 9899 AM1 in 1995. This contained, for example, the wide-character support in wchar.h and wctype.h. Two corrigenda were also published: Technical Corrigendum 1 as ISO/IEC 9899 TCOR1 in 1995 and Technical Corrigendum 2 as ISO/IEC 9899 TCOR1 in 1996. The continuous development and growth made it necessary to work out a new standard, which contains the new features and fixes the known defects and deficiencies of the language. As a result, ISO/IEC 9899:1999 was born in 1999. Similarly to the other standards, this is referred after the publication year as C99. The improvements include the following: .Bl -bullet -offset indent .It Inline functions .It Support for variable length arrays .It New high-precision integer type named long long int, and other integer types defined in stdint.h .It New boolean data type implemented in stdbool.h .It One line comments taken from the C++ language .It Some new preprocessor features .It New variables can be declared anywhere, not just in the beginning of the program or program blocks .It No implicit int type .El .Pp Since then new standards have not been published, but the C language is still evolving. New and useful features have been showed up in the most famous C compiler: GNU C. Most of the UNIX-like operating systems use GNU C as a system compiler, but those addition in GNU C should not be considered as standard features. .Sh SEE ALSO .Xr c89 1 , .Xr c99 1 , .Xr cc 1 .Sh STANDARDS .Rs .%A ANSI .%T X3.159-1989 .Re .Pp .Rs .%A ISO/IEC .%T 9899:1990, Programming languages -- C .Re .Pp .Rs .%A ISO/IEC .%T 9899 AM1 .Re .Pp .Rs .%A ISO/IEC .%T 9899 TCOR1, Programming languages -- C, Technical Corrigendum 1 .Re .Pp .Rs .%A ISO/IEC .%T 9899 TCOR2, Programming languages -- C, Technical Corrigendum 2 .Re .Pp .Rs .%A ISO/IEC .%T 9899:1999, Programming languages -- C .Re .Sh HISTORY This manual page first appeared in .Fx 9.0 . .Sh AUTHORS This manual page was originally written by .An Gabor Kovesdan Aq Mt gabor@FreeBSD.org . Index: head/share/man/man9/OF_device_from_xref.9 =================================================================== --- head/share/man/man9/OF_device_from_xref.9 (revision 332641) +++ head/share/man/man9/OF_device_from_xref.9 (revision 332642) @@ -1,91 +1,91 @@ .\" .\" Copyright (c) 2018 Oleksandr Tymoshenko .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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 9, 2018 .Dt OF_DEVICE_FROM_XREF 9 .Os .Sh NAME .Nm OF_device_from_xref , -.Nm OF_xref_from_device, +.Nm OF_xref_from_device , .Nm OF_device_register_xref .Nd "manage mappings between xrefs and devices" .Sh SYNOPSIS .In dev/ofw/ofw_bus.h .In dev/ofw/ofw_bus_subr.h .Ft int .Fn OF_device_register_xref "phandle_t xref" "device_t dev" .Ft device_t .Fn OF_device_from_xref "phandle_t xref" .Ft phandle_t .Fn OF_xref_from_device "device_t dev" .Sh DESCRIPTION .Pp When a device tree node references another node, the driver may need to get a device_t instance associated with the referenced node. For instance, an Ethernet driver accessing a PHY device. To make this possible, the kernel maintains a table that maps effective handles to device_t instances. .Pp .Fn OF_device_register_xref adds a map entry from the effective phandle .Fa xref to device .Fa dev . If a mapping entry for .Fa xref already exists, it is replaced with the new one. The function always returns 0. .Pp .Fn OF_device_from_xref returns a device_t instance associated with the effective phandle .Fa xref . If no such mapping exists, the function returns NULL. .Pp .Fn OF_xref_from_device returns the effective phandle associated with the device .Fa dev . If no such mapping exists, the function returns 0. .Sh EXAMPLES .Bd -literal static int acmephy_attach(device_t dev) { phandle_t node; /* PHY node is referenced from eth device, register it */ node = ofw_bus_get_node(dev); OF_device_register_xref(OF_xref_from_node(node), dev); return (0); } .Ed .Sh SEE ALSO .Xr OF_node_to_xref 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . Index: head/share/man/man9/printf.9 =================================================================== --- head/share/man/man9/printf.9 (revision 332641) +++ head/share/man/man9/printf.9 (revision 332642) @@ -1,180 +1,183 @@ .\" .\" Copyright (c) 2001 Andrew R. Reiter .\" Copyright (c) 2004 Joerg Wunsch .\" 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 ``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 November 18, 2015 .Dt PRINTF 9 .Os .Sh NAME -.Nm printf , uprintf , tprintf, log +.Nm printf , +.Nm uprintf , +.Nm tprintf , +.Nm log .Nd formatted output conversion .Sh SYNOPSIS .In sys/types.h .In sys/systm.h .Ft int .Fn printf "const char *fmt" ... .Ft void .Fn tprintf "struct proc *p" "int pri" "const char *fmt" ... .Ft int .Fn uprintf "const char *fmt" ... .Ft int .Fn vprintf "const char *fmt" "va_list ap" .In sys/syslog.h .Ft void .Fn log "int pri" "const char *fmt" ... .Ft void .Fn vlog "int pri" "const char *fmt" "va_list ap" .Sh DESCRIPTION The .Xr printf 9 family of functions are similar to the .Xr printf 3 family of functions. The different functions each use a different output stream. The .Fn uprintf function outputs to the current process' controlling tty, while .Fn printf writes to the console as well as to the logging facility. The .Fn tprintf function outputs to the tty associated with the process .Fa p and the logging facility if .Fa pri is not \-1. The .Fn log function sends the message to the kernel logging facility, using the log level as indicated by .Fa pri , and to the console if no process is yet reading the log. .Pp Each of these related functions use the .Fa fmt parameter in the same manner as .Xr printf 3 . However, .Xr printf 9 adds two other conversion specifiers. .Pp The .Cm \&%b identifier expects two arguments: an .Vt int and a .Vt "char *" . These are used as a register value and a print mask for decoding bitmasks. The print mask is made up of two parts: the base and the arguments. The base value is the output base expressed as an integer value; for example, \e10 gives octal and \e20 gives hexadecimal. The arguments are made up of a sequence of bit identifiers. Each bit identifier begins with an integer value which is the number of the bit (starting from 1) this identifier describes. The rest of the identifier is a string of characters containing the name of the bit. The string is terminated by either the bit number at the start of the next bit identifier or .Dv NUL for the last bit identifier. .Pp The .Cm \&%D identifier is meant to assist in hexdumps. It requires two arguments: a .Vt "u_char *" pointer and a .Vt "char *" string. The memory pointed to by the pointer is output in hexadecimal one byte at a time. The string is used as a delimiter between individual bytes. If present, a width directive will specify the number of bytes to display. By default, 16 bytes of data are output. .Pp The .Fn log function uses .Xr syslog 3 level values .Dv LOG_DEBUG through .Dv LOG_EMERG for its .Fa pri parameter (mistakenly called .Sq priority here). Alternatively, if a .Fa pri of \-1 is given, the message will be appended to the last log message started by a previous call to .Fn log . As these messages are generated by the kernel itself, the facility will always be .Dv LOG_KERN . .Sh RETURN VALUES The .Fn printf and the .Fn uprintf functions return the number of characters displayed. .Sh EXAMPLES This example demonstrates the use of the .Cm \&%b and .Cm \&%D conversion specifiers. The function .Bd -literal -offset indent void printf_test(void) { printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE"); printf("out: %4D\en", "AAAA", ":"); } .Ed .Pp will produce the following output: .Bd -literal -offset indent reg=3 out: 41:41:41:41 .Ed .Pp The call .Bd -literal -offset indent log(LOG_DEBUG, "%s%d: been there.\en", sc->sc_name, sc->sc_unit); .Ed .Pp will add the appropriate debug message at priority .Dq Li kern.debug to the system log. .Sh SEE ALSO .Xr printf 3 , .Xr syslog 3